---
title: "Troubleshooting"
description: "Answers to common install, import, thread, and sandbox questions"
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: Answers to common install, import, thread, and sandbox questions
Related: /docs/cli, /docs/agent/mcp, /docs/threads/run, /docs/sandboxes/resources

# Troubleshooting

Short answers to the questions we see most, each with a link to the page that covers the topic in depth.

## Why isn't `hoplite` on my PATH?

The native installer installs to `~/.local/bin` and does not modify your shell configuration. Use the full path — `$HOME/.local/bin/hoplite` — or add that directory to your shell configuration before using the bare `hoplite` command. See [CLI](/docs/cli) for the installer details.

## Why does npx report EOVERRIDE?

npm is validating the current repository's `package.json` before Hoplite starts. Run the command from a temporary directory instead:

```bash title="terminal"
cd "$(mktemp -d)" && npx -y @usehoplite/cli onboard
```

When running from a pnpm project, prefer `pnpm dlx @usehoplite/cli onboard` so pnpm's workspace protocols are understood. See [CLI](/docs/cli).

## Why are my imported MCP servers disabled?

`hoplite onboard` imports MCP **server addresses only** by default — auth headers and OAuth tokens stay on your machine, so those servers arrive disabled and marked **needs credentials**. To use them right away, accept the CLI's separate "Import auth state into Hoplite?" step, or add credentials in **Settings → MCP servers**. Nothing in that step is selected by default, and nothing uploads until you confirm. See [MCP servers](/docs/agent/mcp) for the encryption model.

## Why doesn't Codex OAuth import?

Codex stores its per-server OAuth tokens in a way that would raise a macOS permission prompt to read, so the CLI does not read them. Codex API-key headers are offered as usual. For Codex OAuth servers, add credentials in **Settings → MCP servers** instead. See [CLI](/docs/cli).

## Why are my local changes missing after a handoff?

The cloud workspace can only see files available from GitHub. Without `--autopush`, `hoplite handoff` warns when uncommitted changes or unpushed commits will be missing; run `hoplite handoff --autopush` to commit all local changes and push the branch first. Running development processes and ignored files are never transferred. See [Handoff](/docs/cli/handoff).

## Why is my thread waiting or blocked?

Sensitive actions — file edits, shell commands, disruptive sandbox operations — pause for your approval before executing, and the thread's status tells you when it needs you. Approve or deny the pending action inline to unblock the run. See [Review and approve work](/docs/threads/review) for the approvals model and [Manage threads](/docs/threads/manage) for statuses.

## Why did my run stall, and how do I retry?

If a run stalls on an empty credit balance, an **Add credits** dialog appears right in the thread so you can top up and retry without losing your place — see [Billing](/docs/workspace/billing). For stopping, steering, and retrying runs in general, see [Run a thread](/docs/threads/run).

## Why did setup run the wrong command?

Scripts resolve across two layers: a Hoplite override wins if set (including `enabled: false` to disable a script), and the repo's `.hoplite/settings.json` applies when the override is `null`. The agent's `project_settings_get` tool prints exactly how each script resolves across the two layers, so "why did setup run that?" is always answerable. See [Project settings](/docs/workspace/project-settings) and [Project scripts](/docs/sandboxes/scripts).

## Why did my setup script fail?

Scripts run non-interactively in a fresh environment. Anything they need — package manager, language runtime, database — should either be declared in the repo (lockfiles, `.node-version`, etc.) or installed by the setup script itself. See [Project scripts](/docs/sandboxes/scripts).

## Why did my sandbox run out of disk?

The default platform disk ceiling is 10 GiB. Daytona compatibility workspaces automatically grow their disk by 50% when they report `ENOSPC`, rounded up and capped at the effective ceiling; setup then retries once because dependency installation is safe to repeat, while other failed commands are never replayed automatically. Modal, the default provider for new workspaces, does not support disk resizing — the agent reports that axis as unsupported instead of claiming a change was applied. See [Resources](/docs/sandboxes/resources).

## Why did my dev server stop after a resize?

Modal resizes CPU and memory by replacing the sandbox with a snapshot restore. The change takes a couple of minutes and restarts running processes — the agent is told this so it can restart dev servers afterwards. Hoplite never assumes running background processes survived a disruptive change. See [Resources](/docs/sandboxes/resources).

## Why can't the agent push a repository with submodules?

Publication paths reject repositories with tracked submodules before pushing. This is part of the credential model that keeps GitHub tokens out of the sandbox — see [Tools](/docs/agent/tools).

## Why does a deleted workspace still show a Pending VM cost?

Daytona can post final billing records up to 48 hours late, so a deleted workspace's VM cost may remain **Pending** during that settlement window rather than showing an inaccurate final zero. See [Billing](/docs/workspace/billing).

## Sitemap

See the full [sitemap](/docs/sitemap.md) for all pages.
Well-known sitemap: [/docs/.well-known/sitemap.md](/docs/.well-known/sitemap.md).