Troubleshooting

The backend doesn't start

• MONGODB_URI is not set or MONGODB_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.