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

Port Already in Use

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

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
• Open an issue in the Agent Canvas repository
• Browse the Agent Canvas source