Troubleshooting
Something not working? Start with the quick triage below, then jump to the specific issue.
zoarkbot statusThis shows gateway health, channel connections, and config state. Read the output carefully — it usually tells you exactly what is wrong.
zoarkbot logsLive log stream. Look for ERROR lines — they have the root cause.
If ZoarkBot does not reply to your Telegram messages:
Check if the gateway is running:
zoarkbot statusIf status shows stopped or unreachable, start it:
zoarkbot startCheck logs for errors:
zoarkbot logsIf the gateway is running but still no response, check that your username is in channels.telegram.allowFrom in your config.
Mission Control at mc.zoarkai.org uses your gateway access token to authenticate.
Get your access token:
zoarkbot tokenCopy the full token string printed to the terminal.
Go to mc.zoarkai.org, click Connect Gateway, and paste the token.
Tokens are long random strings (not your license key). If you do not have a token yet, run zoarkbot start to generate one.
If your Telegram bot exists but does not reply:
Verify the bot token in your config matches what @BotFather gave you.
Make sure you started the bot in Telegram — open the bot and send /start.
Check that your Telegram username or ID is in channels.telegram.allowFrom.
Restart ZoarkBot after any config change:
zoarkbot restartDownload links from your account page expire after 15 minutes for security.
Go back to your account page at app.zoarkai.org/account.
Click Download ZoarkBot again to generate a fresh link.
Download immediately — the link is single-use and time-limited.
If your license key is being rejected:
Verify the format is exactly: ZOARKBOT-XXXX-XXXX-XXXX-XXXX (with dashes, uppercase)
Check there are no extra spaces — copy-paste directly from your account page.
If you see license not found: your key may be tied to a different email. Log in with the email you used to purchase.
If the key shows as expired, your subscription may have lapsed. Check your account page or contact [email protected].
If you see an error like Gateway start blocked: set gateway.mode=local:
Set the gateway mode directly:
zoarkbot config set gateway.mode localThen start the gateway:
zoarkbot startRe-running the setup wizard can overwrite your gateway.mode setting. Use zoarkbot config set gateway.mode local to fix it directly.
If the gateway will not start after you edited ~/.zoarkbot/zoarkbot.json:
Check the exact error:
zoarkbot statusCommon causes: JSON syntax error (missing comma, extra bracket), unknown config key, wrong value type.
Restore your backup if you made one:
cp ~/.zoarkbot/zoarkbot.json.bak ~/.zoarkbot/zoarkbot.jsonThen restart:
zoarkbot restartStill stuck? We are here to help.
[email protected]