Troubleshoot a task

Start with the run's current status and error. Keep its session and run IDs when reporting a problem. Do not include tokens, secret values, or private authentication files in a support message.

Run stuck queued

Check these in order:

1. Project image: confirm it is qualified, or inspect the build failure. A run can be accepted before its image is ready.
2. Runner target: confirm that the project targets the execution capacity you actually have.
3. Runner availability: for a self-hosted runner, check Docker and the devboxes listen process.
4. Model access: check the selected account and the runner's available provider credentials.
5. Project and blueprint requirements: repair missing repository access, inputs, or integration bindings.

Use devboxes doctor on the execution machine for setup diagnostics. Increasing listener concurrency does not repair a missing dependency. Do not dispatch the same task again just because its accepted run is queued.

No models are available

Check Credentials → Models and the local runner's credential status. Verify that the selected account supports the requested provider and model. An account can be connected but invalid, unavailable, disabled, or rate-limited.

Use the repair action shown for that account. Subscription sign-ins and API keys can require different recovery steps.

The repository is missing

Check the Git host and connection selected in the project picker. For GitHub, confirm selected-repository access and any required permission approval. For a manual token, check the repository permissions and expiry. Reload the repository list after repairing access.

The transcript stopped updating

Check whether the run is still active. A connection problem in the browser can interrupt live updates while execution continues. Reload the session to read retained history. Avoid force-stopping work solely because the live stream disconnected.

The run is blocked

Open the session and inspect the current step, questions, and review state. Provide the requested input or repair the named requirement. A blocked state is not a terminal result.

The run finished without a pull request

Read its outcome and blueprint. Some workflows produce a summary or file rather than a pull request. Others can complete work but fail to publish it. Inspect published results, publication failures, the branch, and the transcript before retrying.

A CLI result is not ready

devboxes result <session-id> exits with status 1 while the run is not terminal. Read status again later. Once terminal, inspect runStatus and the outcome: failure and cancellation are terminal states too.

You cannot open a session

Confirm the signed-in account, organization, and membership. An ordinary session URL does not grant access. A read-only share may have expired or been revoked. Ask the person who shared it to check the appropriate access path.