Fix common problems

devboxes is down

Check status.devboxes.ai first. It shows whether the devboxes API and its dependencies, the docs, and devboxes Nixhub answer. It runs separately from devboxes, so it stays reachable during an outage.

The CLI says you are not signed in

Run devboxes login.

The sign-in code does not work

A code works once and expires after 5 minutes. After three wrong tries it stops working. Run devboxes login --email <address> again for a new code.

If the CLI answers TWO_FACTOR_REQUIRED, your account uses two-factor authentication. Sign in with your password instead: run devboxes login and choose email and password.

The browser refuses the code from the CLI

When you sign in with GitHub or Google, the CLI shows a code that you approve in the browser. When the browser can't approve it, the page says why:

The CLI lists sign-in methods and stops

Outside a terminal, the CLI cannot ask how you want to sign in. Add --github, --google or --email to devboxes login. See Sign in.

A delegation token stopped working

The token expired, or you or an Organization owner revoked it. Removing a member from the Organization revokes all of their delegations, and a Run's delegation ends when the Run ends. delegations.list shows when your delegations expire and which ones were revoked. Create a new delegation. For CI, create one with no expiry.

A call says you are not allowed

Your role in the Organization does not allow that operation. Ask an owner or admin to run it or to change your role. If you use a delegation token, create a new delegation that lists the operation.

A call says that an ID was not found

Check that the ID belongs to the Organization in organizationId. List the resources, for example with projects.list, and copy the ID again.

A task does not start

To check it yourself:

1. Read the Run's queueReason with sessions.inspect. workspace_image means that the Run waits for the Project's workspace, retry means that devboxes starts the Run again after a problem on its side, and capacity means that capacity that devboxes manages has no room yet. See Follow a task.
2. Check that the Project's Runner is running. capacity.list shows it as ready. If it is offline, start the Runner on the machine again, as shown in Add a Runner.
3. Check the Project's workspace with images.inspect. A task waits for a workspace build only when the Project has no workspace yet, when it was started to wait for a new workspace, or when its Runner's platform needs a workspace built for it. When the build failed, its failureMessage says why. While tasks wait on a Project's first workspace, devboxes builds it again by itself when it failed on its side, up to three times, and once more whenever devboxes updates its image builder; after those tries, run images.configure with the same packages and services. When the image builder rejected the packages or services, those tasks wait until a later images.configure builds.
4. Check that the model account still works with connections.list.

Work does not start because devboxes paused new Runs

DISPATCH_HALTED means that devboxes has paused new Runs while it resolves an operational issue, for every Organization or for yours. The pause is temporary. Start the work again later. A Run that was queued before the pause stays queued and starts once the pause ends. Runs that already run continue, unless devboxes also stops them. Then the Run's error says so, its stoppedBy is halt, and the Session keeps the work saved so far. Continue the Session once the pause ends.

Managed work does not start for lack of credit

COMPUTE_CREDIT_EXHAUSTED means that your plan's included usage and your prepaid credit are used up. The message names the date when the plan's included usage renews. Buy credit or subscribe to a plan, or choose one of your own Runners for the Project.

When credit runs out while work runs, devboxes stops the work, and the Run's error says so. The Session keeps the work saved so far. Continue the Session once your Organization has credit again.

Managed work does not start because too many Runs are running

MANAGED_CONCURRENCY_REACHED means that your Organization already has as many managed Runs at once as its plan allows. Start the work again when one of them ends, move to a larger plan, or choose one of your own Runners for the Project. Runs on your own Runners don't count.

You can't buy credit

TOP_UP_LIMIT means that the purchase is above what your plan lets you buy now. Plans and billing lists the limits. To have your limit raised, write to [email protected].

A managed Run failed on devboxes' side

When a managed Run fails because of devboxes, for example because its machine went away, devboxes' team gets an alert, and in Chat, devboxes says so. devboxes doesn't charge the Run until it has looked at it. Continue the Session to try again.

A task failed

Read the Run's error and summary with sessions.inspect. Then give the Session a corrected instruction with sessions.continue, or start a new task.

The model provider refused a task

When the model provider refused the task's model account, the task fails, and the Session's conversation shows the failed step with the provider's refusal. devboxes pauses the account for an hour:

From the CLI, replace the account's key or sign-in with devboxes connect --account <account id>, as Connect a model account describes. Then send the agent a message.

The agent did not push its work

Only a publish node pushes the agent's commits. Check with sessions.inspect whether the task's publish node was skipped or failed. A publish node is skipped when the step before it, for example the tests, failed. If the Blueprint has no publish node, add one and commit a new version. See Write a Blueprint.

devboxes does not answer in Chat

To check it yourself:

1. Check that Chat is on with chat.policy.
2. Check that the channel is assigned to a Project with chat.channels.
3. Check that the devboxes app is a member of the channel.

You do not know whether a write went through

Before you run a write again, read what it changes. Running sessions.dispatch twice starts two tasks.