Troubleshooting

Find the section that matches what failed, and keep the visible error message handy. If the recovery steps don't help, contact support with that message and the project or thread where it happened.

Desktop looks stuck or out of date

If the titlebar shows Offline or Reconnecting, check your computer's network connection. Threads and machine status will catch up when the connection returns. For a view that remains stale, press Cmd+R to reload the desktop app.

If you closed the main window, choose File → Show Workbench. If you're stuck on a page and can't return to the workbench, sign out and sign back in.

A devbox or Template box stops responding

If the desktop app responds but the selected machine doesn't, first confirm that you've selected the affected devbox or Template box. Then try these steps in order:

1. Click the CPU or memory meter. If a process is using excessive resources, stop that process from the process view.
2. If the machine still doesn't respond, choose Machine → Reset. This will stop shells, agent sessions, background commands, and user services while keeping your files.
3. If Reset fails, choose Machine → Reboot. Reboot will preserve files but stop every process, agent session, terminal, service, and connection on that machine.

Wait for a reboot to finish before starting another. If the result says the machine is sleeping, choose Wake. If the machine restarted but services aren't ready, wait briefly, then try Reset or contact support. See Sleep, wake, and recover for more recovery options.

Inspect Activity to see which processes are using the machine's resources. Select the image to enlarge it.

Setup scan, upload, or access failed

Return to your existing setup under Setups in progress in the desktop project menu. You can also choose Continue setup on its row in the setup wizard's Project step.

A scan missed something or stopped

Open the scan group with the missing items, describe what it should include, and choose Send feedback & rescan. Review the new findings before approving them. For a failed or stopped scan, use Retry scan.

If a scan is taking too long, choose Stop in its header. You can retry that scan later; stopping it will preserve other scans and completed reviews.

An upload or remote setup step failed

An interrupted upload will try to reconnect and resume automatically. If Retry upload appears, use it; confirmed uploaded parts will be kept.

For a temporary remote setup failure, use Retry setup when offered. If you stopped the setup agent yourself, choose Open setup thread and ask it to continue. Stopping the agent will leave setup paused until you continue the conversation.

Git access failed

For local-folder setup, choose Fix Git access when offered. This will remove the incomplete Template box and return you to Finalize Bundle while keeping your approved review and bundle choices. Restore the named GitHub account's repository access, or choose SSH and register the displayed public key with your Git host before verifying it. You can also skip Git access and configure it after setup.

For Create from GitHub, follow the error's access action: reconnect the original GitHub account, grant the boxes.dev GitHub App access to the named repositories, or restore your write permission. An organization owner may need to approve the access request. Retry after access is restored. If repository policy requires SSH, cancel and restart this setup with Use an SSH key for GitHub pull/push access instead.

Use Rebuild bundle when setup asks you to prepare the upload again. If it returns to Git access, verify the displayed key before continuing.

Setup asks you to start over

Use the setup's start-over action if it says the saved setup can no longer be used. Your original folder on your computer will remain; boxes.dev will rebuild the pending setup and upload bundle. For a payment block, resolve the issue in Billing before retrying.

Member-project preparation needs attention

If a member project shows GitHub access needs review, choose Review GitHub access. Reconnect the intended account or grant the boxes.dev GitHub App access to every named repository, then retry. This project type requires that access; it won't switch to SSH or an older Team Template version.

For a saved environment or setup failure, open View details, choose Copy details, and send them to a team admin. Your unsent draft and attachments will remain available to retry after the problem is fixed. Existing devboxes remain usable. A startup script warning has a different recovery path, described below.

An optional MCP connection can show a warning without blocking your first thread. Follow that warning's sign-in or retry action. Required GitHub access and sign-in for the selected coding agent must be ready before work can start. See Maintain a Team Template.

A new devbox warns about its startup script

If a new devbox's thread warns that its startup script failed or timed out, the devbox still started; the warning describes that script run's result. Review the script's outcome before relying on it, then dismiss the warning. Dismissing acknowledges that exact result, and a different failure will warn again. The script is the project's Startup Script under Project settings → Devbox lifecycle.

In a Member project, the team script runs first with your connections and files available, followed by your project's script. Either failure will show a warning while the next script and agent continue; both results remain inspectable if both fail. For a team script, open or copy its details and contact a team admin. Admins can choose Review startup script to open its setting. Startup script failures won't pause other members' devbox creation.

A corrected script will apply to future devboxes. On this devbox, run the needed repair in Terminal or ask the agent; waking it or opening another thread won't rerun startup.

Codex, Claude, or an MCP needs sign-in

For a Codex or Claude sign-in error, use the thread's refresh action when offered. Otherwise, reconnect the affected account from Configure agents in the desktop app, or from the mobile app's Reconnect banner or Settings → Agent accounts. Check now will check the account without waking a machine. Needs re-auth means the provider rejected the saved login; an incomplete status check alone doesn't disconnect your account.

If Claude's browser sign-in page shows an error, retry on that page or cancel the attempt in boxes.dev and start again. You don't need to restart the desktop app.

To repair Codex sign-in from a terminal, run dvb setup --agents on your own computer. Don't run codex login or codex logout inside a Template box or devbox. After reconnecting, return to the thread and reply to continue.

An MCP connection needs attention

If a slow MCP reconnection delays a message to an existing Claude thread in the desktop app, boxes.dev will keep the message queued and send it when Claude is ready, even after a wait of more than a minute. You don't need to send it again. For a sign-in error, follow the steps below.

Open Integrations → MCPs, then select the Codex or Claude button on the affected connection. If sign-in shows Status unknown, choose Retry status check to check the same attempt, or Cancel to start over.

For servers installed on the Template box, open Template-managed MCPs and choose Retry if the list won't load. This may wake the Template box. A dash in the server count means the list is unavailable; it doesn't mean no servers are installed. Member projects don't have this Template box inventory.

An older desktop version may offer a dvb mcp authorize command. Run it on your own computer, not inside a Template box or devbox.

An agent stopped before finishing

If a large Codex thread asks you to reload or update boxes.dev, press Cmd+R in the desktop app. Reloading won't stop the agent on the devbox. On mobile, open Settings → About → Release details and choose Check for update. If the message persists and no compatible update is available, install the latest app version or contact support.

If Retry says the thread is too large, send a new message to continue. The failed turn stays in your history.

If the message says an older thread is too large to reopen, start a new thread to continue. Updating the app does not remove this limitation for older threads.

Use the failure message to choose the next action:

• Model capacity or temporary rate limit: wait briefly before continuing, or choose another available model.
• Credits: add credits or wait for them to renew in your agent account.
• Sign-in: reconnect the affected agent account.
• Machine networking: continue after the machine can reach the agent provider.
• Internal, rejected-request, or execution errors: read the error details before continuing, and include them if you contact support.

After a Codex response fails, reply in the same thread to continue. Codex retains the message and attachments it received; you do not need to send them again. If it may already have changed files, ask it to inspect the current files before continuing. Retry for a message that has not been delivered is a separate recovery action.

For Claude, Resend is available only when boxes.dev can confirm that Claude never received the message. If delivery is uncertain, read the conversation before sending the request again. See Recover from a failed start or message.

A devbox will not start or wake

Read the failure message before retrying:

• If you've reached the awake devbox limit, sleep an idle devbox to make room. Sleeping won't delete it.
• If billing blocks compute, open Billing. A team admin may need to update payment, assign a paid seat, or add usage credits.
• If a snapshot or saved Team Template version is unavailable, follow the message's recovery action. Contact support if it offers no way to continue.

Waking can take many seconds or a few minutes. Wait for the attempt to finish. If it fails, the machine returns to Sleeping; use its wake control to retry. With auto-wake enabled, selecting the machine again after 15 minutes can also trigger one new attempt.

If repeated attempts fail and no billing or capacity block is shown, contact support with the project, devbox, and approximate time.

If moving a thread from the Template box failed, its menu may offer Move back to Template box. If a recovery notice says the machine was restored after an unexpected stop, inspect its files and Git status before continuing: changes made after the restored snapshot may be missing.

Billing or a plan limit blocks work

If you're not a team admin, send the billing message to an admin. Depending on the block, they may need to add a payment method, renew or change the plan, assign a paid seat, buy usage credits, or configure automatic credit reload. For a project limit, you'll need room for another project or a plan that allows more projects. For the available options, see Plans, seats, and box-hours.

Ports, files, or Git are missing

Select the devbox or Template box that contains the work and wake it if needed. Each devbox has separate files and services, so selecting another machine can show a different repository state or an empty ports menu. For a commit that shows the wrong name or email, go to A commit has the wrong author.

A port is missing or won't open

Wait for the selected machine to report its ports, then check that your development server is running on that machine. If an ordinary forwarded port can't open because your computer already uses that port, choose Use next available, or stop the local process using it. A stable Local URL keeps its exact port instead of offering another one: boxes.dev reports the conflict, and you can free the local port or turn off Local URLs for that devbox to return to ordinary forwarding.

GitHub rejects a fetch, pull, or push

Follow the error's recovery action to reconnect the original GitHub account, restore your write permission, or grant the boxes.dev GitHub App access to the repository.

If only pushes changing .github/workflows fail, choose Update GitHub access for each affected installation, then return to boxes.dev to check again. You can also use SSH. Ordinary Git operations can keep working while that additional permission is pending.

A commit has the wrong author

Open Account settings and inspect Git identity. Unless you saved an override, it uses your connected GitHub account's name and private no-reply email. Then run these commands in the affected repository to see which configuration file supplies the name and email:

git config --show-origin --get user.name
git config --show-origin --get user.email

Repository settings take precedence over machine-wide settings, which take precedence over the Account identity. Change the setting at the scope you intend: Account for your shared default, git config --global for this machine, or git config --local for this repository.

If Account reports a failed update for a saved override, choose Retry. GitHub defaults retry automatically. Active machines will update; sleeping machines will catch up when they next wake. If Git reports an invalid configuration file, repair the named file; changing the Account identity won't fix it.

GitHub CLI authentication failed

Wake the affected machine, then open Integrations → GitHub. If you want gh to use your connected boxes.dev GitHub account, turn on GitHub CLI in devboxes. GitHub can be connected while this setting is off — desktop setup offers the choice separately — so check the switch even when pull and push already work. Complete any reconnect or machine update the page requests.

Use Manage repository access to check that your GitHub account and the boxes.dev GitHub App can reach every known repository in the project. If your organization can't approve the App for one of them, authorize personal access instead. Managed gh sign-in becomes available for the project when one authorization — the App or your personal access — covers every known repository; boxes.dev doesn't combine the two across repositories.

While this managed access is active, change the account through boxes.dev instead of running gh auth commands. When the setting is off, GitHub isn't connected, or repository access is missing, gh uses credentials configured on the machine and you can use gh auth login there.

The GitHub CLI in devboxes setting is separate from automatic Git fetch, pull, and push access.

Automations, Slack, or Linear did not start work

For a saved automation, open it and inspect its recent runs. If a run hit the awake devbox limit, sleep an idle devbox or reduce the number of simultaneous runs. For a billing block, resolve the issue in Billing. After fixing the cause, retry through the original trigger, or choose Run now if it is available. For work that should have started from Slack or Linear, start with that integration's section below.

Separate Slack requests and Linear assignments can start work at the same time, so a burst of requests can exhaust available devbox capacity.

Slack

Open Team Settings → Slack to check the workspace connection. If it's missing, revoked, or lacks required permissions, ask a team admin to connect or reinstall the integration.

If Slack says your account isn't linked, send connect to the @boxes.dev app in Slack. For a missing channel, add the app to that channel, then choose Recheck in Team Settings. Confirm that the automation is active and permits that channel and user.

For missing attachments, check that the file is still available in Slack and the bot can access its channel. Slack file import also has size and sender restrictions; see Slack.

Linear

Open Team Settings → Linear and choose Check. If access was revoked, permissions changed, or the connection remains invalid, a team admin needs to reconnect Linear. For the full setup steps, see Linear.

If new assignments don't start work, link your Linear identity in Account settings and confirm that your default assignment automation is active. Existing issues can continue their threads, but new assignments require both a working workspace connection and your linked identity.