Troubleshooting¶

Common problems with Agent Zero 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:

On the instance, check the service and the UI:

sudo systemctl is-active agent-zero-core.service
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:5080/

If it is not active, read the log:

sudo journalctl -u agent-zero-core.service --no-pager -n 50

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

The service keeps restarting¶

Cause: The container fails to start, for example because of low memory or disk, or wrong ownership on the state folder.

Fix: Read the log, and check the state folder:

sudo journalctl -u agent-zero-core.service --no-pager -n 50
sudo stat -c '%a %u:%g' /var/lib/agent-zero-core/usr

The folder should be 700 10000:10000. Use at least 4 GiB of RAM and a 40 GiB root volume.

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. "Ready" in the setup wizard only means settings were saved.

Fix: Correct the key and models in settings, check your quota with the provider, and allow outbound HTTPS to the provider. Repeat the test task.

A plugin cannot be turned on¶

Cause: The plugin is not part of Core.

Fix: This is expected. See Plugins for the list.

The Telegram helper rejects the file¶

Cause: Common reasons:

the file is not owned by root, or its mode is not exactly 0600;
it has fields other than token, allowed_private_chat_ids and bot_name;
the token format is wrong;
allowed_private_chat_ids is empty, has duplicates, or holds anything other than positive numbers written as strings;
bot_name has uppercase letters, spaces or other characters.

Fix: Correct the file and run the helper with --check-only again.

`Native Telegram configuration failed`¶

Cause: The helper could not apply the configuration inside the container. Common reasons:

agent-zero-core.service is not running;
a bot with a different bot_name is already configured. Each instance supports one bot.

Fix: Check that the service is active. Use the same bot_name as the existing bot, or use a separate instance for the other bot.

Telegram is silent¶

Check, in order:

You enabled polling with --enable.
You wrote from a private chat whose ID is in allowed_private_chat_ids.
Nothing else polls the same bot, and the bot has no webhook.
Your model works in the web UI.
The instance can reach Telegram over outbound HTTPS.