Troubleshooting
#The backend doesn't start
MONGODB_URI is not setorMONGODB_DATABASE is not set. Both are required; see Environment variables.- It crashes on bson. You run it on Bun older than 1.4.3. Use the published image, or Bun 1.4.3 or later.
#The setup link points to allay.chat
/allay init builds the link from PUBLIC_URL, which falls back to https://allay.chat. Set PUBLIC_URL in the environment to the address you open in a browser, restart, and run /allay init again.
#The plugin gets 401 everywhere after updating to 6.0
A 6.0 backend wants every plugin request identified. On a self-hosted backend, set PLUGIN_TOKEN (24 characters or more) and put the same value in the plugin's server.token; TOKEN_NOT_SET means the backend has none. On a hosted backend the plugin needs Allay 6.0, which sends its license, or makes one when it brings its own key.
#/allay init answers that the backend isn't self-hosted
The backend runs with billing on. Set SELFHOSTED=1 and restart. A backend with billing on prints its setup code to its own log instead.
#The panel's saved keys are gone after an update
The backend sealed them with a key in /data/secrets.key, and the container lost it. Set SECRETS_KEY, or mount /data as a volume, then enter the keys again.
#Sign-in fails over plain http
The panel's cookie is Secure everywhere but localhost. Put the backend behind https, or open it at http://localhost.
#Error codes the plugin shows
| Code | What it means | What to do |
|---|---|---|
PROVIDER_AUTH_FAILED |
The provider refused the key | Check the key in the plugin's provider.byok.api_key |
MODEL_NOT_FOUND |
The provider doesn't know the model | Check the model's name |
MODEL_NO_TOOLS |
The model can't call tools | Pick a model that can; perplexity/sonar* only searches |
PROVIDER_URL_REJECTED |
The base URL isn't https, or points into a private network | Use a public https address |
RATE_LIMITED |
Too many questions from this server with its own key | Wait retry_after seconds |
LICENSE_REQUIRED, LICENSE_INVALID |
A hosted backend got no license, one it doesn't know, or one it revoked after a refund (since 6.3) | Run /allay link; after a revoke, delete license.key first. With your own key, Allay 6.0 makes one by itself |
TOKEN_REQUIRED, TOKEN_INVALID |
A self-hosted backend got no token, or the wrong one | Set server.token to the backend's PLUGIN_TOKEN |
TOKEN_NOT_SET |
The self-hosted backend has no PLUGIN_TOKEN |
Set one of 24 characters or more, and the same in server.token |
SUBSCRIPTION_INACTIVE, QUOTA_EXCEEDED |
Nothing paid for now, or the period's limit is spent | Pay again, or wait for resets_at |
PLAYER_BLOCKED |
The backend's admins blocked this player on this server (since 6.2) | An admin unblocks them on the player's page in the panel |
TOOL_TIMEOUT |
The plugin didn't answer a tool call in time | Raise TOOL_TIMEOUT_MS, or check the Minecraft server's load |
#A perplexity/… model as the main model
Such a model can't call tools, so the backend moves it to search and answers with the default model. Set a tool-capable model in OPENROUTER_API_MODEL and the online one in SEARCH_MODEL.
#More than one instance
The backend keeps pending tool calls in its process's memory, so it runs as one instance. With several, a tool result must reach the instance that holds the stream.