Skip to main content
Version: 1.0.0

Troubleshooting

This guide starts from common symptoms. For detailed codes, read the diagnostics reference.

zsh: command not found: code​

The VS Code terminal command is missing from PATH. On macOS, enable it from the Command Palette, then open a new terminal. code and the touba CLI are separate commands; reinstalling Touba does not configure code.

To install the extension without a terminal, search for @id:touba.touba-tools in VS Code’s Extensions view, then select Install.

zsh: command not found: touba​

Likely cause:

  • the Touba VS Code extension is installed, but the Touba CLI is not available in the terminal PATH.

Key point:

  • the VSIX installs Touba Language Toolkit;
  • it does not automatically create the terminal commands touba, touba run, touba compile, touba inspect, touba manifest, or touba handler stub;
  • install the CLI from Installation, then open a new terminal;
  • for a simple .tb file, use the VS Code command Touba: Run Current File;
  • for touba init, touba prepare, or runtime commands, use an environment where the Touba CLI is explicitly available.

The Runtime Refuses a Tool Before the Handler​

Likely causes:

  • missing manifest;
  • missing binding;
  • missing grant;
  • unresolved secret;
  • invalid payload.

Actions:

Terminal
touba inspect program.air.json --manifest touba.manifest.json
touba run program.air.json --manifest touba.manifest.json --inputs-json '{"request":{}}'

Read failure_detected in the trace or CLI error.

touba prepare --mode check Fails​

Likely causes:

  • source module outside convention;
  • missing manifest while a tool exists;
  • missing binding;
  • missing handler stub;
  • expected grant, secret, or memory access absent;
  • binding left in the manifest after the tool was removed.

Actions:

Terminal
touba prepare --mode plan
touba prepare --mode write
touba prepare --mode check

Read diagnostics before adding a grant or secret. prepare must not broaden rights silently.

PreparedAirDrift identifies missing AIR or AIR that differs from the expected preparation. An unchanged write no longer causes check to request another AIR write. HandlerDeclaredContractDrift identifies stale generated-stub contracts (grants, secrets, arguments or return type). Update the handler explicitly: write preserves your code. Generated contract tests check admission and structural refusals; add a positive test for your business logic.

The Handler Does Not Receive a Secret​

Check:

  • the tool declares secrets HANDLE;
  • the binding contains "secrets": ["HANDLE"];
  • the binding contains the expected grant;
  • the secrets file is supplied at execution;
  • the environment variable exists;
  • if an agent is active, the agent scope authorizes this handle.

ask Remains Paused​

Touba does not read stdin.

Provide the input explicitly:

Terminal
touba run program.air.json --user-inputs user-inputs.json

For a manual test, use the interactive host mode:

Terminal
touba run program.air.json --interactive-user-inputs

The interaction reference is visible in the pause trace.

A Live Test Fails​

A live test depends on network, the external service, quotas, and sometimes an API key.

Start with a dry run when one exists, then move to live only to validate the real integration.

Traces Seem to Miss a Value​

This is sometimes expected.

Traces must not contain:

  • secret values;
  • exact ask answers in user_interaction_answered;
  • refused sensitive payloads.

They must contain the references, handles, modes, and refusal reasons needed for audit.