---
title: "Troubleshooting"
description: "Find the failing stage and recover setup, agent runs, previews, or the CLI."
canonical_url: "https://hoplite.sh/docs/workspace/troubleshooting"
markdown_url: "https://hoplite.sh/docs/workspace/troubleshooting.md"
---

# Troubleshooting
URL: /docs/workspace/troubleshooting
LLM index: /llms.txt
Description: Find the failing stage and recover setup, agent runs, previews, or the CLI.
Related: /docs/threads/run, /docs/sandboxes/scripts, /docs/sandboxes/resources, /docs/cli

# Troubleshooting

Start with the failing stage: workspace setup, agent execution, preview process, or local CLI. A failed preview does not necessarily mean the agent run failed, and an interrupted client does not necessarily stop cloud work.

## Setup fails or runs the wrong command

1. Expand the workspace-setup entry in the thread timeline. Read the failing stage and available log output.
2. Check **Settings → Project → Environment** for an override. It takes precedence over the repository's `.hoplite/settings.json`.
3. Correct the command or missing dependency. Setup is non-interactive, so include required runtime installation and supply secrets through project environment variables.
4. Retry the thread and check that setup completes before the next agent step.

The agent can inspect effective script configuration through `project_control` with `op: "settings_get"`. [Script resolution](/docs/sandboxes/scripts#how-scripts-resolve) describes disabling and clearing overrides.

## A thread is waiting or stops progressing

Check the pending-action bar first. A tool approval or required question pauses execution until it is answered. An expired approval requires a new message to resume work; see [approval expiry](/docs/threads/review#approvals).

If the thread reports a billing block, inspect the workspace balance, monthly usage limit, and thread lifetime spend limit. These are separate controls. Adding credits does not raise a spending cap. See [Billing](/docs/workspace/billing) and [thread limits](/docs/threads/cost#lifetime-spend-limit).

For a failed run, inspect its recorded error before using `/retry`. `/stop` requests cancellation and displays **Stopping** until the worker finishes; it is unavailable during protected workspace setup.

## A preview crashes or stops after resizing

Open the Preview panel and inspect its state, exit reason, and available run-log tail. Check that the run command starts the expected service and that its listening port matches the configuration.

Archiving and disruptive CPU or memory changes stop running processes. Start the managed preview again after the workspace is ready. Repeated startup failures require correcting the command, dependencies, or resource limit; see [Previews](/docs/sandboxes/previews#preview-states).

## The workspace runs out of disk

Inspect the reported disk usage and provider capability before requesting a resize. Modal workspaces do not support disk resizing. Daytona compatibility workspaces can grow disk within the configured ceiling when `ENOSPC` is reported.

After an automatic disk increase, setup retries once. Other failed commands are not automatically replayed. Remove only disposable files or adjust the project configuration, then rerun the failed command. See [Resources](/docs/sandboxes/resources).

## The CLI is not on PATH

`npm i -g @usehoplite/cli` installs `hoplite` into npm's global bin directory. If your shell can't find it, check that the directory printed by `npm prefix -g` (plus `/bin`) is on your PATH. Homebrew installs into `$(brew --prefix)/bin`.

If you unpacked a release archive yourself, keep `hoplite` and `hoplite-legacy` in the same directory. Commands such as `login`, `onboard`, and `handoff` otherwise fail with "needs the hoplite-legacy helper"; set `HOPLITE_LEGACY_BIN` to the helper's path if it has to live elsewhere.

## The CLI can't find the project

The CLI picks the Hoplite project from the repository's GitHub remote. The error says which step failed:

| Message | Fix |
| --- | --- |
| "is not linked to a Hoplite project" | Link the repository to a project in Hoplite, or set `HOPLITE_PROJECT_ID` |
| "no GitHub repository detected for this directory" | Run from a checkout with a GitHub remote, or set `HOPLITE_PROJECT_ID` |
| "matches multiple Hoplite projects" | Set `HOPLITE_PROJECT_ID` to the one you want |
| "was not found in any signed-in Hoplite organization" | Sign in to that project's workspace with `hoplite login --org SLUG` |

`hoplite acp` takes `--project ID` for the same purpose. See [Configuration](/docs/cli/configuration#environment-variables).

## The CLI asks you to sign in again

"not signed in to Hoplite" or "Hoplite rejected the stored CLI key" means no CLI key is stored for this API, or Hoplite no longer accepts the stored one: it expired, was revoked, or was stored by CLI 2.x, whose keys lack the permissions sessions need. Run `hoplite login`. The interactive CLI, `hoplite ask` and `hoplite exec` in a terminal, and `hoplite acp` do this by themselves once; `hoplite ask` and `hoplite exec` in a script can't open a browser, so they stop and ask you to run `hoplite login` once after upgrading. If the browser doesn't open, for example over SSH, open the printed sign-in URL in a browser on any machine and confirm the code it shows. Set `HOPLITE_BROWSER=none` to only print the URL.

When you're signed in to several workspaces, `hoplite login --org SLUG` picks the default one for directories that don't identify a project.

## The CLI can't reach Hoplite

The interactive session shows one notice and keeps retrying in the background; prompts sent meanwhile fail and are not queued. `hoplite ask` fails at once with the reason. Check your network, proxy, or VPN, and check that `HOPLITE_BASE_URL` isn't set to a server you no longer use. A run that was already going continues in Hoplite; see [Offline and reconnecting](/docs/cli/interactive#offline-and-reconnecting).

## /merge, /autofix, or /automerge is refused

Merging a pull request and changing the review loop need the `repo:update` permission. Workspace owners and admins have it and members don't, in the CLI as in the Hoplite app. The CLI key gets it when an owner or admin signs in, so if you were made an admin after signing in, run `hoplite login` again.

## npx reports EOVERRIDE

npm can reject the current repository's package configuration before Hoplite starts. Run from a temporary directory:

```bash title="Run outside the repository"
cd "$(mktemp -d)"
npx -y @usehoplite/cli onboard
```

For pnpm repositories, `pnpm dlx @usehoplite/cli onboard` understands pnpm workspace protocols. Successful startup reaches the CLI import flow rather than npm's package validation error.

## Imported MCP servers are disabled

Imports copy server addresses without credentials by default. Add credentials under **Settings → Project → MCP**, or explicitly select the CLI's auth-state import step. Hosted runs expose remote HTTP/SSE servers only; a local `stdio` entry will not add tools to the hosted agent.

Codex OAuth tokens are not imported when reading them would require a macOS permission prompt. Configure those credentials in Hoplite instead. See [MCP servers](/docs/agent/mcp).

## Local changes are missing after handoff

The cloud workspace starts from GitHub. Uncommitted files, unpushed commits, ignored files, and local processes are not part of a normal handoff.

Push the intended branch before handing off. `hoplite handoff --autopush` explicitly commits all local changes and pushes first; review what will be included before using it. See [Handoff](/docs/cli/handoff).

## Deleted workspaces still show Pending VM cost

Daytona's final billing records can arrive up to 48 hours after deletion. **Pending** means final provider charges have not settled. Check the billing record again after settlement; deleting the workspace does not erase usage already incurred.

## Sitemap

Sitemap discovery is not enabled for this deployment.