> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-client-message-context.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fix common Agent Canvas install, startup, backend, model, workspace, and uninstall issues.

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:

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    node --version
    npm --version
    uv --version
    agent-canvas --help
    ```

    If one command fails, fix that prerequisite first. See [Install](/openhands/usage/agent-canvas/setup).
  </Tab>

  <Tab title="Docker">
    ```bash theme={null}
    docker --version
    docker ps
    ```

    If `docker ps` cannot connect to the Docker daemon, start Docker Desktop or Docker Engine and try again.
  </Tab>
</Tabs>

## `agent-canvas` Command Not Found

If `agent-canvas` is not available after installation:

1. Confirm the package installed successfully. You should see `@openhands/agent-canvas` followed by the version if it has been installed:

   ```bash theme={null}
   npm list -g --depth 0
   ```

2. Check your npm global install prefix:

   ```bash theme={null}
   npm prefix -g
   ```

3. Make sure the npm global `bin` directory is on your `PATH`.

   <Tabs>
     <Tab title="macOS / Linux">
       Find the npm global `bin` directory:

       ```bash theme={null}
       echo "$(npm prefix -g)/bin"
       ```

       Check whether your shell can already find `agent-canvas`:

       ```bash theme={null}
       which agent-canvas
       ```

       If `which agent-canvas` prints nothing, check your current `PATH`:

       ```bash theme={null}
       echo "$PATH"
       ```

       If the npm global `bin` directory is missing, add it for the current terminal session:

       ```bash theme={null}
       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`.
     </Tab>

     <Tab title="Windows PowerShell">
       Find the npm global install prefix:

       ```powershell theme={null}
       npm prefix -g
       ```

       Check whether PowerShell can already find `agent-canvas`:

       ```powershell theme={null}
       Get-Command agent-canvas
       ```

       If `Get-Command` cannot find it, inspect your current `PATH`:

       ```powershell theme={null}
       $env:Path -split ';'
       ```

       The npm global package directory, or the `bin` directory for your Node.js installation, needs to appear in that list.
     </Tab>
   </Tabs>

4. Try running without a global install:

   ```bash theme={null}
   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:

1. Install `uv` from the [official uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).

2. Open a new terminal so your shell reloads its `PATH`.

3. Verify the install:

   ```bash theme={null}
   uv --version
   ```

4. Start Agent Canvas again:

   ```bash theme={null}
   agent-canvas
   ```

## Browser Does Not Open Or Shows A Blank Page

Agent Canvas listens on `http://localhost:8000` by default.

If nothing opens automatically:

1. Open `http://localhost:8000` manually.

2. Check the terminal running Agent Canvas for startup errors.

3. If port `8000` is busy, start on another port:

   ```bash theme={null}
   agent-canvas --port 3000
   ```

4. 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:

```bash theme={null}
agent-canvas --port 3000
```

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

```bash theme={null}
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:

1. Start Docker Desktop on macOS or Windows, or start Docker Engine on Linux.

2. Verify Docker is running:

   ```bash theme={null}
   docker ps
   ```

3. Run the Agent Canvas Docker command again.

On Windows, use PowerShell command syntax from [Install](/openhands/usage/agent-canvas/setup#install-and-run). PowerShell uses backticks (`` ` ``) for line continuation instead of backslashes.

## Backend Is Unreachable

If Agent Canvas loads but the active backend is disconnected:

1. Open the backend switcher and select `Manage Backends`.
2. Verify the backend host URL.
3. Verify the API key if the backend requires one.
4. Switch to the default local backend if available.
5. 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 Profiles and Model Configuration](/openhands/usage/agent-canvas/llm-profiles)
* [LLM Settings](/openhands/usage/settings/llm-settings)
* [Local LLMs](/openhands/usage/llms/local-llms)
* [LiteLLM Proxy](/openhands/usage/llms/litellm-proxy)

## `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:

1. The `LLM Provider` field is set.
2. The model ID matches that provider.
3. Any custom `Base URL` is correct for the provider or local model server.
4. 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](/openhands/usage/llms/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:

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

See [ACP Agents](/openhands/usage/agent-canvas/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:

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

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

## 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:

1. Confirm it is saved on the active backend.
2. Confirm any required secrets are saved under `Settings > Secrets`.
3. 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:

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

See [Pre-built Automations](/openhands/usage/agent-canvas/prebuilt-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.

<Tabs>
  <Tab title="npm">
    Stop the running process with `Ctrl+C`, then update or uninstall:

    ```bash theme={null}
    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.
  </Tab>

  <Tab title="Docker">
    Stop the container before updating or removing the image:

    ```bash theme={null}
    docker ps
    docker stop <container-id-or-name>
    docker pull ghcr.io/openhands/agent-canvas:latest
    docker rmi ghcr.io/openhands/agent-canvas:latest
    ```
  </Tab>
</Tabs>

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:

* [Join the OpenHands Slack community](https://openhands.dev/joinslack)
* [Open an issue in the Agent Canvas repository](https://github.com/OpenHands/agent-canvas/issues)
* [Browse the Agent Canvas source](https://github.com/OpenHands/agent-canvas)