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

# Troubleshooting

> Common Agent Canvas setup and runtime issues, plus places to ask for help.

Use this page for the most common Agent Canvas problems.

## Command Not Found

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

* confirm the package installed successfully with `npm install -g @openhands/agent-canvas`
* make sure your npm global bin directory is on your `PATH`
* run `agent-canvas --help` to confirm the binary resolves correctly

## Missing `uv`

Agent Canvas relies on `uv` to run the local agent server stack.

If startup fails because `uv` or `uvx` is missing, install it from the official guide:

* [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/)

## Port Already in Use

Agent Canvas listens on port `8000` by default. If that port is busy, start it on another one:

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

## Backend Is Unreachable

If Agent Canvas cannot talk to the active backend:

* open `Manage Backends`
* verify the backend host or base URL
* verify the API key if the backend requires one
* switch to another backend to confirm the issue is backend-specific

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

## MCP Settings Are Missing

MCP configuration does not live under `Settings`.

Open the top-level `Customize` area, then go to `MCP Servers`.

## Automation Features Are Unavailable

If the `Automations` view shows an unavailable or unhealthy state, the active backend may not have a working automation service.

Start with the default local backend to confirm the UI works, then debug the remote backend separately.

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