Troubleshooting

Find the message you see, then follow What to do. Headings quote the app's wording, so you can search this page for it. For API error types, see Errors.

Collect details

Run these on the machine with the problem before you change anything.

1. Check the daemon:

   openllm status

   It shows whether the service is registered and running, a live status check, and the file paths it uses.

2. Run the diagnostics. Without flags this changes nothing:

   openllm doctor

   To remove leftover install files and managed config regions, run openllm doctor --fix. Your own settings in those files are kept. To add an AI diagnosis, run openllm doctor --ai; it sends the redacted report and recent daemon logs through your gateway.

3. Read the daemon logs:

   openllmd logs -n 200
   openllmd logs -f

   The files are in ~/.openllm: openllmd.log, plus openllmd.out.log and openllmd.err.log from the service. On Linux with the systemd user service, openllmd logs reads the journal instead.

4. Check the configuration the CLI resolved:

   openllm config --json

5. If support asks for a diagnostic report, run openllm doctor report. It asks the daemon to upload its sanitized diagnostic events, not raw logs. Preview the export first with openllm doctor report --dry-run.

For a failed API request, keep the response headers. x-openllm-chain and x-openllm-resolved-model show which models were tried, and a 500 carries a reference id in x-openllm-error-ref.

Vault

Vault locked

What you see: Vault locked or Locked to your vault on a device ("Unlock vault to connect to this device"), or Your vault is locked on a key.

Cause: your vault is locked in this browser. The app needs it unlocked to read your API keys and to open channels to devices that only accept vault-signed channels. Nothing is wrong with the device or the key. Requests that tools send with an sk-llm- key keep working.

What to do

• Select Unlock vault and enter your PIN, or use your passkey.
• To change how long the vault stays unlocked, see Security.

This key belongs to a previous vault

What you see: This key belongs to a previous vault, or Old key on a device. Requests with the key fail with 401 auth_error "Not authenticated".

Cause: the key was created under an older recovery phrase. After a vault reset, nothing can decrypt it, so every request made with it is rejected.

What to do

1. On Devices & keys, select Create a new key. Your vault must be unlocked.
2. Give the new key to every tool that used the old one. On a machine with the daemon, run openllm login and paste it.
3. Delete the old key.

See Reset your vault for what a reset changes.

This browser's vault copy is out of date

What you see: This browser's vault copy is out of date, or Old browser.

Cause: your vault was reset in another browser, and this browser still holds the old copy. Your keys and devices are untouched.

What to do

• Select Enter recovery phrase and enter your 12-word recovery phrase. This fixes the whole browser at once.

Couldn't decrypt this key

What you see: Couldn’t decrypt this key.

Cause: either the key predates your current recovery phrase, or this browser holds an out-of-date vault copy. The app can't tell which yet.

What to do

1. Unlock with your recovery phrase.
2. If the key still fails, replace it as in This key belongs to a previous vault.

Devices & daemon

Device offline

What you see: This device is offline, or Offline in the device picker ("No daemon is running on that machine right now").

Cause: no daemon has checked in from that machine recently. The machine may be asleep, or the daemon stopped.

What to do

1. On that machine, run openllm status.
2. If the daemon isn't running, run openllm start.
3. If it is running but stays offline, read openllmd logs -n 200 for connection errors.

The device comes back on its own once the daemon reconnects. See Devices.

Sessions off

What you see: Remote sessions are off, or Sessions off ("Run "openllmd sessions on" on that machine").

Cause: the machine can host device chat, but remote terminal sessions are off. They are off after a plain curl install and when the Mac app connects the machine. Add a device turns them on unless you switch Remote terminal off.

What to do

• On that machine, run:

  openllmd sessions on

  If the device still shows Sessions off, run openllm restart there. A running daemon can keep its old setting.

• Or run openllm login --pty-sessions there. It asks for your API key again, saves the key and the setting together, and restarts a running daemon.

• Or turn on Remote terminal and re-pair the device.

Seed gate pending

What you see: Seed gate pending, or Seed gate ("The daemon hasn't picked up its device access yet").

Cause: device access is provisioned, but the daemon hasn't loaded it yet.

What to do

• Wait. It resolves on its next bootstrap.
• To speed it up, run openllm restart on that machine.

Daemon identity changed

What you see: Daemon identity changed, or Reset identity ("The daemon key changed; reset its cloud identity before using RTC").

Cause: the daemon on that machine has a new identity key that doesn't match the one pinned to its API key, so direct connections fail.

What to do

1. On Devices & keys, select Reset daemon identity for that device.
2. Wait for the daemon's next status update; it re-registers on its own.

Not secured

What you see: Not secured yet, or Not secured ("This device isn't bound to your recovery phrase yet").

Cause: the device works, but it isn't bound to your recovery phrase. Once secured, only an unlocked vault can open channels to it.

What to do

• Unlock your vault, then select Secure device on Devices & keys.

You're using all your devices

What you see: You're using all your devices ("… devices connected at once — run openllmd stop on one to free a slot"). The daemon on the new machine gets 403 device_limit_exceeded.

Cause: your plan's limit on devices connected at the same time is reached. Only running daemons count.

What to do

• On a machine you aren't using, run openllm stop (or openllmd stop). Unpairing doesn't free a slot; stopping the daemon does.
• The waiting daemon connects on its own once a slot frees.
• For more devices, see Device limits.

Connection issue

What you see: Connection issue ("The browser couldn't open a channel to that machine").

Cause: the machine is online, but this browser couldn't reach it directly or through the relay. The device still serves API requests.

What to do

• Try again in a moment.
• If it persists, check the network between the browser and the machine, and read openllmd logs on the machine.

Providers & sign-in

A provider sign-in fails

What you see on Providers or during onboarding, and what to do:

To sign in from the terminal instead, list the providers and their login methods, then start the login. Use --method device on a machine without a browser, if the provider offers it.

openllm auth providers
openllm auth login claude_code
openllm auth status claude_code

Starting a login is not the same as signing in; check openllm auth status afterward. See Subscriptions.

Subscription models fail from the hosted gateway

What you see: 403 subscription_requires_daemon with "This chain resolves only to subscription providers … no online device of yours can serve them".

Cause: subscription models run only on your devices, and no online device is signed in to that provider.

What to do

1. Start the daemon on a machine signed in to the provider: openllm start.
2. Check the sign-in with openllm auth status.
3. Or add an API-key model to the chain in Configuration. See Routing.

For local models the type is local_requires_daemon. See Errors.

Clients

openllm: command not found

Cause: the install couldn't add openllm to your PATH, or your shell hasn't reloaded.

What to do

1. Run ~/.openllm/bin/openllm setup.
2. Open a new terminal.

A client uses the hosted gateway instead of the daemon

Cause: the CLI uses the local daemon only when it answers on OPENLLM_DAEMON_PORT; otherwise it uses the hosted gateway. A set OPENLLM_GATEWAY overrides this.

What to do

1. Run openllm status and start the daemon if needed.
2. Check openllm config --json for the port, and unset OPENLLM_GATEWAY in your shell.

Leftover config after uninstalling or moving

What to do

• Run openllm doctor to list leftovers, then openllm doctor --fix to remove the ones OpenLLM owns.

See Clients for per-client common problems.

API requests

401 "Not authenticated"

Cause: the key is missing, mistyped, deleted, or from a previous vault.

What to do

• Send Authorization: Bearer sk-llm-… or x-api-key: sk-llm-…. See Authentication.
• Check the key still exists on Devices & keys. If it's an old key, see This key belongs to a previous vault.

You've used your free tokens this month

What you see: You've used your free tokens this month ("… monthly tokens used — your free budget resets on …"), or 402 free_tier_exhausted from the API. At 80% the app warns first: You've used …% of your free tokens.

Cause: your Free plan has used its monthly tokens.

What to do

• Wait for the reset on the 1st of the month (UTC), or upgrade to Pro in Settings → Billing. See Monthly tokens.

500 with a reference id

What you see: 500 internal with "Internal server error (ref: …)".

What to do

• Retry once. If it repeats, send the reference id to support as below.

Still stuck

Contact support with:

• what you did and what you expected,
• the exact message, or the API error type,
• the error reference id from x-openllm-error-ref or the message, if you have one,
• the output of openllm status and openllm doctor.

Email [email protected], or ask in the community Discord. Discord is public, so don't post keys, recovery phrases, or logs that contain them.

Last updated on