Troubleshooting - OpenHands Docs

Use this page when Agent Canvas does not start, the browser cannot reach it, the backend is disconnected, model setup fails, or uninstall/update commands get stuck.

Start With These Checks

Run the checks for the install method you used:

npm
Docker

node --version
npm --version
uv --version
agent-canvas --help

If one command fails, fix that prerequisite first. See Install.

docker --version
docker ps

If docker ps cannot connect to the Docker daemon, start Docker Desktop or Docker Engine and try again.

`agent-canvas` Command Not Found

If agent-canvas is not available after installation:

Confirm the package installed successfully. You should see @openhands/agent-canvas followed by the version if it has been installed:
npm list -g --depth 0
Check your npm global install prefix:
npm prefix -g
Make sure the npm global bin directory is on your PATH.
- macOS / Linux
- Windows PowerShell
Find the npm global bin directory:
echo "$(npm prefix -g)/bin"
Check whether your shell can already find agent-canvas:
which agent-canvas
If which agent-canvas prints nothing, check your current PATH:
echo "$PATH"
If the npm global bin directory is missing, add it for the current terminal session:
export PATH="$(npm prefix -g)/bin:$PATH"
To make the change permanent, add that export line to your shell profile, such as ~/.zshrc or ~/.bashrc.
Find the npm global install prefix:
npm prefix -g
Check whether PowerShell can already find agent-canvas:
Get-Command agent-canvas
If Get-Command cannot find it, inspect your current PATH:
$env:Path -split ';'
The npm global package directory, or the bin directory for your Node.js installation, needs to appear in that list.
Try running without a global install:
npx @openhands/agent-canvas

If npx works but agent-canvas does not, the issue is usually your shell PATH.

Missing `uv` Or `uvx`

Agent Canvas uses uv to run the local agent server stack. If startup fails because uv or uvx is missing:

Install uv from the official uv installation guide.
Open a new terminal so your shell reloads its PATH.
Verify the install:
uv --version
Start Agent Canvas again:
agent-canvas

Browser Does Not Open Or Shows A Blank Page

Agent Canvas listens on http://localhost:8000 by default. If nothing opens automatically:

Open http://localhost:8000 manually.
Check the terminal running Agent Canvas for startup errors.
If port 8000 is busy, start on another port:
agent-canvas --port 3000
Open http://localhost:3000.

If the browser page loads but stays blank, refresh once and check the terminal for frontend or backend startup errors.

Port Already In Use

If startup says port 8000 is already in use, run Agent Canvas on another port:

agent-canvas --port 3000

If you are using Docker, map a different host port:

docker run -it --rm \
  -p 3000:8000 \
  -v ~/.openhands:/home/openhands/.openhands \
  -v ~/projects:/projects \
  ghcr.io/openhands/agent-canvas:latest

Then open http://localhost:3000.

Docker Daemon Not Running

If Docker commands fail with a daemon or connection error:

Start Docker Desktop on macOS or Windows, or start Docker Engine on Linux.
Verify Docker is running:
docker ps
Run the Agent Canvas Docker command again.

On Windows, use PowerShell command syntax from Install. PowerShell uses backticks (`) for line continuation instead of backslashes.

Backend Is Unreachable

If Agent Canvas loads but the active backend is disconnected:

Open the backend switcher and select Manage Backends.
Verify the backend host URL.
Verify the API key if the backend requires one.
Switch to the default local backend if available.
Check the terminal or server logs for backend startup errors.

For the default local setup, you usually do not need to manually enter a backend API key. Agent Canvas can generate and persist one locally. For --public, VM, Modal, or other remote backends, use the LOCAL_BACKEND_API_KEY configured for that backend. Anyone with that key can access the backend, so keep it private.

Wrong Backend URL Or API Key

Backend URLs should point to the Agent Canvas backend ingress, not to an unrelated local service. Common examples:

Setup	Typical URL
Default local Agent Canvas	`http://localhost:8000`
Local backend on another port	`http://localhost:8001`
Docker mapped to host port `8000`	`http://localhost:8000`
VM or reverse proxy	Your VM, proxy, or ngrok URL

If you changed the port with --port, use the port you selected.

Model Or API Key Errors

If a conversation fails before the agent responds, check Settings > LLM. Common causes:

The API key is missing or expired.
The selected provider does not match the model name.
A custom or local model is missing the correct base URL.
A LiteLLM proxy token is invalid.
An OpenAI-compatible provider needs the provider, model, base URL, and key to line up.

For model setup details, see:

`LLM Provider NOT provided`

This error usually means the configured model name does not include enough provider information, or the provider field is not set. Fix it by opening Settings > LLM and confirming:

The LLM Provider field is set.
The model ID matches that provider.
Any custom Base URL is correct for the provider or local model server.
The API key or token is valid.

If you are using Ollama, LM Studio, LiteLLM, or another OpenAI-compatible endpoint, use the provider and base URL expected by that service. See Local LLMs.

ACP Agent Credentials Are Not Used

ACP agents such as Claude Code, Codex, and Gemini CLI can be used in place of an LLM API key. If an ACP agent does not authenticate:

Confirm the provider CLI is signed in on the same machine where the backend runs.
If the backend runs in Docker, on a VM, or in cloud infrastructure, do not assume it can see your laptop’s CLI login.
Add the required API key or secret for that backend.
Reopen or restart the conversation after changing agent settings.

See ACP Agents for the credential rules.

Workspace Is Not Where You Expected

The agent works in the workspace attached to the conversation. If file changes appear in the wrong place or the agent cannot find your project:

Use Open Workspace before starting the conversation.
Confirm the conversation is using the backend you expect.
For Docker, make sure the project is under the mounted projects directory, such as ~/projects, which appears as /projects inside the container.
For a VM backend, remember that the agent sees files on the VM, not files on your laptop.
For a cloud backend, use the cloud workspace or repository flow for that backend.

Do not expose broad filesystem mounts or sensitive directories unless you are comfortable with the agent reading and writing files there.

MCP Settings Are Missing

MCP configuration does not live under Settings. Open the top-level Customize area, then go to MCP Servers. If a configured MCP server is not available to the agent:

Confirm it is saved on the active backend.
Confirm any required secrets are saved under Settings > Secrets.
Restart or start a new conversation if the server was added after the conversation began.

Automation Features Are Unavailable

Automations run on the active backend. If the Automations view shows an unavailable or unhealthy state:

Switch to the default local backend and check whether automations work there.
Confirm the remote backend includes the automation service.
Check the backend logs for automation startup errors.
Confirm required MCP servers and secrets are configured on the same backend as the automation.

See Pre-built Automations.

LLM Profiles Do Not Match OpenHands Cloud

Agent Canvas currently has fuller support for LLM profiles than the hosted OpenHands Cloud UI. If profiles appear in Agent Canvas but not in OpenHands Cloud directly, that can be expected while the Cloud rollout is still in progress. Profiles and settings are also scoped to the active backend, so switching backends can change which profiles are available.

Update Or Uninstall Is Stuck

Before updating or uninstalling, stop Agent Canvas.

npm
Docker

Stop the running process with Ctrl+C, then update or uninstall:

npm install -g @openhands/agent-canvas@latest
npm uninstall -g @openhands/agent-canvas

On Windows, if uninstall fails because uv.exe or another file is in use, close terminals running Agent Canvas, stop related processes, and retry.

Stop the container before updating or removing the image:

docker ps
docker stop <container-id-or-name>
docker pull ghcr.io/openhands/agent-canvas:latest
docker rmi ghcr.io/openhands/agent-canvas:latest

Uninstalling the package or image does not automatically delete persisted settings, secrets, or conversation history. Those live in the persistence directory you used, such as ~/.openhands.

Get Help

If you are still stuck:

​Start With These Checks

​agent-canvas Command Not Found

​Missing uv Or uvx

​Browser Does Not Open Or Shows A Blank Page

​Port Already In Use

​Docker Daemon Not Running

​Backend Is Unreachable

​Wrong Backend URL Or API Key

​Model Or API Key Errors

​LLM Provider NOT provided

​ACP Agent Credentials Are Not Used

​Workspace Is Not Where You Expected

​MCP Settings Are Missing

​Automation Features Are Unavailable

​LLM Profiles Do Not Match OpenHands Cloud

​Update Or Uninstall Is Stuck

​Get Help

Start With These Checks

`agent-canvas` Command Not Found

Missing `uv` Or `uvx`

Browser Does Not Open Or Shows A Blank Page

Port Already In Use

Docker Daemon Not Running

Backend Is Unreachable

Wrong Backend URL Or API Key

Model Or API Key Errors

`LLM Provider NOT provided`

ACP Agent Credentials Are Not Used

Workspace Is Not Where You Expected

MCP Settings Are Missing

Automation Features Are Unavailable

LLM Profiles Do Not Match OpenHands Cloud

Update Or Uninstall Is Stuck

Get Help