Skip to content

Troubleshooting

Common problems with OpenHands Core, what causes them and how to fix them.

The UI does not load

Cause: The service is still starting, has failed, or the tunnel is not running.

Fix:

  1. On the instance, check the service and readiness:

    sudo systemctl is-active sushi-openhands.service
curl -s http://127.0.0.1:8000/ready

  2. If it is not active, read the log:

    sudo journalctl -u sushi-openhands.service --no-pager -n 50

  3. Make sure your SSH or Session Manager tunnel is still open, and open http://127.0.0.1:8000/canvas/.

First startup can take several minutes.

The service keeps restarting

Cause: The container fails to start, often because of low memory or disk.

Fix: Check NRestarts and the log:

sudo systemctl show sushi-openhands.service -p ActiveState -p SubState -p NRestarts
sudo journalctl -u sushi-openhands.service --no-pager -n 50

Use at least 4 GiB of RAM and a 32 GiB root volume. Do not start a second container to work around it.

The agent does not answer, or reports an authentication or quota error

Cause: The provider key, model or quota is wrong, or the instance cannot reach the provider.

Fix: Correct the key and model in Agent Canvas settings, check your quota with the provider, and allow outbound HTTPS to the provider. A running service does not mean inference works; repeat the test task.

Claude returns a configuration error on a small task

Cause: Extended thinking stays on by default. With a low output-token limit, the thinking budget falls below Anthropic's minimum.

Fix: In the agent profile, set reasoning effort to none and the extended thinking budget to 0.

Telegram is silent

Check, in order:

  1. The bridge is running:

    sudo systemctl status sushi-openhands-telegram.service
sudo journalctl -u sushi-openhands-telegram.service --no-pager -n 50

  2. The configuration validates:

    sudo python3 /opt/sushi/bin/openhands-telegram.py \
  --config /etc/sushi/openhands-telegram.local.json --check-config

  3. You wrote in the allowed private chat, from an allowed user, and started the message with /task.

  4. Nothing else polls the same bot, and the bot has no webhook.
  5. The agent profile UUID exists and its model works in the UI.
  6. The instance can reach Telegram over outbound HTTPS.

Do not clear the bridge state to force a retry.

The Telegram check fails

Cause: --check-config prints Bridge stopped safely: followed by an error type, without showing any values. Common reasons:

  • the file is readable by other users or is a symbolic link;
  • expected_bot_id does not match the digits before : in bot_token;
  • chat_id is zero, or authorized_user_ids is empty;
  • agent_profile_id is not a valid UUID;
  • canvas_url is not a plain http://127.0.0.1 address;
  • max_iterations is outside 1 to 20, or task_timeout outside 1 to 600.

Fix: Correct the file, make it root-only, and check again:

sudo chown root:root /etc/sushi/openhands-telegram.local.json
sudo chmod 0600 /etc/sushi/openhands-telegram.local.json
sudo python3 /opt/sushi/bin/openhands-telegram.py \
  --config /etc/sushi/openhands-telegram.local.json --check-config

The agent cannot write to my project

Cause: The project folder is not owned by the container user.

Fix:

sudo chown -R 10001:10001 /var/lib/sushi-openhands/projects/<project>