Troubleshooting

Docker ran out of network address poolsCopy Anchor Link

The installer stops at docker compose up with:

all predefined address pools have been fully subnetted

Docker creates a network for each Compose project, and old projects left their networks behind until no address range is free. The installer recognizes this error and prints the fix. Remove the unused networks and run the installer again:

docker network prune -f
curl -fsSL runelay.com/install | sh

docker network prune only removes networks that no container is using. Your existing .env and data/ folder are kept on the second run.

runelay migrate fails with "Too big"Copy Anchor Link

runelay migrate stops while sending accounts with an error like:

Too big: expected string to have <=2000 characters

Some agents store an OAuth client secret or a scope list longer than 2,000 characters, and older servers rejected the whole import because of it. The limits for imported clientSecret and scope are now 20,000 characters.

Update the server, then run runelay migrate again. Accounts that already work are not touched on a second run.

cd ~/runelay && docker compose pull && docker compose up -d

On the desktop app, download the latest release instead. See Operations.

OAuth window not openingCopy Anchor Link

When you install an OAuth connector, the panel opens a blank tab right away and sends it to the provider's sign-in page. If nothing opens:

• The browser blocked the tab. The connection is still saved and waits for sign-in. Press Finish sign-in on its catalog row, or open /connectors/reconnect. If a new tab still cannot open, the sign-in page loads in the current tab instead.
• The provider refused runelay. Some providers only allow OAuth apps they approved and answer with HTTP 403. runelay shows an error saying so. Use that account directly in the agent, or connect it with a token as a custom connection if the provider supports one.
• The sign-in finishes but the connection stays pending. The provider sends you back to PUBLIC_URL/v1/oauth/callback, and that page needs your panel session. Make sure PUBLIC_URL in .env is the exact address you open the panel at (scheme, host and port), and that you are logged in to the panel in the same browser. Restart after changing it: docker compose up -d.

Port 4312 is already in useCopy Anchor Link

Docker cannot bind the port and docker compose up fails with an error like port is already allocated.

New install. Pick another port when you run the installer. It writes both the port and the matching PUBLIC_URL to .env:

curl -fsSL runelay.com/install | RUNELAY_PORT=4313 sh

Existing install. The installer keeps an existing .env, so edit it by hand. compose.yaml reads RUNELAY_PORT for the published port:

RUNELAY_PORT=4313
PUBLIC_URL=http://localhost:4313

cd ~/runelay && docker compose up -d

Then point the CLI and your agents at the new address with runelay login http://localhost:4313 and runelay connect. OAuth connections signed in through the old PUBLIC_URL may need Finish sign-in again.

Desktop app. The app always runs its server on 127.0.0.1:4312. If a runelay container already answers there, the app refuses to start and asks you to close the other one. If another program holds the port, the app reports that the server did not start; the log is server.log in the app's data folder.

Lost RUNELAY_SECRETCopy Anchor Link

RUNELAY_SECRET is the key for everything runelay encrypts: connection configs (URLs, headers, env values), OAuth tokens and recoverable API keys. They are sealed with AES-256-GCM using a key derived from the secret, and there is no copy anywhere else. The panel login sessions are signed with it too.

Without the original secret:

• The server does not start at all if RUNELAY_SECRET is missing or shorter than 32 characters.
• With a new secret, the server starts and everyone has to log in to the panel again. Memories and skills are not encrypted, so they are all still there.
• Anything that reads connections fails with Failed to read or write the database.: the connections list in the panel, and the tool list your agents get. The old connections cannot be decrypted or removed from the panel. Recoverable API keys can no longer be revealed.

If you have a backup of .env (or of the secret), put the original value back and restart. Everything works again.

If the secret is gone, the connections have to be added again. Stop the server, back up data/, delete the old connection rows from the SQLite database, start it and reconnect each account:

cd ~/runelay
docker compose stop runelay
cp -r data data.backup
sqlite3 data/runelay.db "DELETE FROM sources;"
docker compose up -d

Then reinstall from the catalog or run runelay migrate again.

Keep a copy of RUNELAY_SECRET next to your backups of data/. You need both to restore. On the desktop app the secret is generated for you and stored in the system keychain when one is available.