Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Frequently asked questions

This page answers common questions and errors. For a guided diagnostic path, see Troubleshooting.

Setup

veyyon plugin doctor fails. What do I fix?

veyyon plugin doctor exits non-zero when a check reports an error, and it prints the failed check and the next action. Fix the line it reports, then run it again. For the full diagnostics surface, see Diagnostics and health.

The sandbox is missing or not enforced

Veyyon fails closed when it cannot establish a sandbox. On Linux, the sandbox uses Landlock and seccomp, with a bundled bwrap fallback where the system sandbox is unavailable. On macOS it uses the Seatbelt profile. If you see a sandbox error, check that your kernel and user privileges support one of these mechanisms, or use /elevate-sandbox to walk through the elevated sandbox setup. See Sandbox and approvals for the policies and how they combine with approval settings.

Database and session locking

“Session file is locked” or “another Veyyon process is running”

Veyyon uses file locking to prevent two processes from writing the same session file at once. Only one process may hold a session lock at a time. If you see this error:

  • Check that no other veyyon process is holding the same session file lock.
  • If a previous process crashed, the lock may be stale. Restarting the machine or waiting for the process table to clear usually releases it.
  • Do not delete or edit the session file while a process might still hold it.

For how sessions are stored and resumed, see Sessions.

Model authentication

“Invalid API key” or “Authentication failed”

Veyyon is provider-agnostic and does not proxy your requests. The key is sent directly to the provider you configured. Check that the environment variable or config key matches the provider’s expected name, that it is not expired, and that it has the required permissions. The supported variables are covered in Models and providers.

“Unsupported region” or endpoint errors

The base URL you configured must match the provider region and product endpoint. A model id that exists in one region may not exist in another, and the same hostname may host different model catalogs. Verify the endpoint URL in your provider dashboard and compare it with the base_url in your config. Models and providers explains how provider configuration is resolved.

Why is my model not listed?

Veyyon discovers model ids from the provider’s /models endpoint rather than maintaining a hardcoded allowlist. If a model is not listed, the provider endpoint may not expose it, or your key may not have access to it. Check the provider catalog and your key scopes first.

Workflow

Why did my edit ask for approval?

The approval policy decides when Veyyon must ask before acting. The default policy asks for anything that changes files or runs commands outside the trusted set. If a file edit paused for approval, it means the current policy classifies that edit as needing your yes. You can change the policy with -a, --ask-for-approval or in config.yml. The sandbox and approval policy work together: the sandbox is the hard boundary, and the approval policy is the interaction layer. See Sandbox and approvals.

How do I resume a session?

Run veyyon --continue to continue the most recent session, or veyyon --resume <SESSION_ID> to resume a specific one. The session stores turns, tool activity, and queued follow-ups, so a resumed session should keep its context and any pending work. For branching, forking, or exporting a session, see Sessions.

What happened to my queued follow-up?

Follow-ups queued during a turn are stored server-side with the session, so they survive TUI restarts and session resumes. If you press Esc to interrupt the current turn, queued follow-ups are pulled back into the composer so nothing is lost. See Sessions for the full queue behavior.

Why does my output look truncated?

Output is intentionally truncated when it exceeds a tool budget. The truncation should include a next action, such as increasing a limit, using an offset, or narrowing the search. See Troubleshooting for the public path.

Where to go next