Troubleshoot LLM errors

Common errors you may encounter when using the OPAL chat overlay and how to fix them.

---

Readiness banner messages

These messages appear in the orange banner above the chat input when the LLM is not ready.

"Add your API key to a provider and enable it"

Cause: No providers have credentials configured.

Fix:

1. Open the LLM Registry from the setup menu.
2. Double-click your provider to edit it.
3. Enter your API key in the Credentials field.
4. Click Save.

"Add a model to your enabled provider"

Cause: A provider is enabled but has no models.

Fix:

1. Edit the provider and click Fetch models to import models from the API.
2. Or manually add a model with the correct model ID.

"Set a default model in the LLM Registry"

Cause: Models exist but none is marked as default.

Fix: In the LLM Registry, select a model and click Set default.

"Enable the [provider] provider"

Cause: The default model's provider is disabled.

Fix: Edit the provider and ensure it is enabled (not disabled).

---

"The key of [provider] was sealed by another installation. Enter it again."

Cause: The app seals each API key with a seal key that belongs to this installation. The key in your LLM settings was sealed by another one: for example, you copied the settings from another computer, or the seal key file in the keys folder was removed.

Fix: Open the provider, enter the API key again, and test it. The app does not delete the old sealed key until you enter a new one.

---

"The key of [provider] cannot be read. Enter it again."

Cause: The sealed key in your LLM settings is damaged, so it does not open.

Fix: Open the provider, enter the API key again, and test it.

---

"Enter the base URL of [provider]."

Cause: The provider speaks the OpenAI protocol and has no base URL. Only Anthropic has a default address.

Fix: Open the provider, and enter its base URL. The table of base URLs gives the address of each provider.

Connection test messages

"The server needs a key. Enter the server's key."

Cause: The provider is a self-hosted server with no key, and the server answered 401: it was started with a key.

Fix: Open the provider, click Edit next to the credentials, enter the key that the server was started with, and test again.

"The server loads its model. Test again in a minute."

Cause: The server runs, but it is still loading its model. A large model can take a minute or more.

Fix: Wait a minute, then click Test connection again.

"Nothing answers at [address]. Start the server, or check the address."

Cause: No server listens at that address and port. The server is not running, or the base URL names another machine or port.

Fix: Start the server. If it runs, check the host and the port of the base URL, and check that the server listens on the network and not only on its own machine (for llama.cpp, --host 0.0.0.0).

"Connection returned no models"

Cause: The provider answered, but its list has no model. A server with no loaded model, or a key with no access to any model, does this.

Fix: Load a model on the server, or check the key's access with the provider.

Chat error messages

These appear as red error bubbles in the chat.

"Authentication failed"

Cause: Your API key is invalid, expired, or has insufficient permissions.

Fix:

1. Click the Check API key button in the error bubble to open the provider editor.
2. Verify your API key is correct (no extra spaces, not expired).
3. Click Test connection to verify.
4. If using Anthropic, ensure your key starts with sk-ant-.

"Network error"

Cause: Cannot reach the provider's API endpoint.

Fix:

1. Check your internet connection.
2. If using a custom base URL, verify it is correct and reachable.
3. Check if a firewall or proxy is blocking the connection.
4. Try again later if the provider may be experiencing downtime.

"The provider did not answer in 120 s."

Cause: The provider accepted the request but sent no answer at all for two minutes. A busy server, or one that is still starting, does this.

Fix:

1. Try again in a minute.
2. Check the provider's status page, or for a server of your own, check that it runs.

"The provider stopped sending for 120 s."

Cause: The answer began, and then nothing arrived for two minutes. A long answer that keeps arriving never times out; a silent one does.

Fix:

1. Try again. The part of the answer that arrived is not kept.
2. Check your network connection.

"[provider] refused the key."

Cause: The provider answered 401 or 403: the API key is wrong, expired, or has no access to this model. The provider's own explanation follows the message.

Fix: Open the provider, enter the key again, and select Test connection.

"[provider] limits the requests now."

Cause: The provider answered 429: too many requests in a short time, or the account's limit is reached. When the provider says how long to wait, the message says it too.

Fix: Wait the time that the message names, then try again. If it keeps happening, check your plan with the provider.

"[provider] loads its model. Try again in a minute."

Cause: A llama.cpp server answers 503 while it loads its model, which can take a minute after it starts.

Fix: Wait a minute, then try again.

"Waiting for [provider]: [n] ahead."

Cause: Not an error. The provider is a server of your own that answers one request at a time, and another request is still running. The app sends the next request when a slot of the server is free.

Fix: None needed. To answer more requests at once, start the server with more slots (-np for llama.cpp), and test the provider again so that the app reads the new number.

"No online provider has the model [model]."

Cause: A Trove task or a session asked for a model that no usable online provider lists.

Fix: Fetch the models of the provider that has the model, or enable and test that provider.

"The answer from [provider] stopped before its end."

Cause: The answer began, and the connection then ended without the mark that ends a complete answer. A server that crashed or restarted, or a proxy between you and the server, can do this.

Fix: Try again. If it keeps happening with a server of your own, look at the server's log.

"PDF files need a provider with the Anthropic protocol."

Cause: You attached a PDF, and this provider speaks the OpenAI-compatible protocol, which has no way to send one.

Fix: Use an Anthropic model for this conversation, or paste the text of the PDF into the chat.

"[provider] cannot see images: the model [model] has no vision."

Cause: The chat carries an image, and the selected model has no vision in its settings.

Fix: Select a model with vision, or edit the model and turn vision on if you know that it supports images.

"[provider] cannot be reached"

Cause: Nothing answered at the provider's address. For a server of your own, it may not run, or the address or port is wrong.

Fix: Check that the server runs, and check the base URL in the provider's settings.

"Request timed out"

Cause: The provider took too long to respond.

Fix:

1. Try again -- the server may have been temporarily overloaded.
2. Try a smaller/faster model if available.
3. Check your internet connection speed.

"Model X is no longer available"

Cause: The model has been retired or removed by the provider. Providers periodically remove older model versions.

Fix:

1. Click the Configure model button in the error bubble to open the model editor.
2. In the LLM Registry, look for models marked "Unavailable" in orange. If an upgrade is suggested (shown as "→ model-name"), select that model instead.
3. Click Set default on a working model.
4. Use Fetch models in the provider editor to import the latest available models.

Note: Model availability is checked automatically on startup. Unavailable models are marked transiently — they are re-checked each session because providers may restore models.

"Model returned an empty response"

Cause: The LLM returned no content. This is usually a transient issue.

Fix:

1. Try sending your message again.
2. Try rephrasing your message.
3. If it persists, try a different model.

---

Error action buttons

Some error bubbles include action buttons that navigate directly to the relevant settings:

---

Model availability and upgrades

On each startup, the app checks your stored models against the provider's live model list. Models that are no longer available are marked as "Unavailable" in the LLM Registry.

If a newer version of the same model family exists, the registry shows an upgrade suggestion (e.g. "Unavailable → claude-opus-4-6"). You can use the Remove unavailable button in the registry to clean up retired models.

If your default model becomes unavailable, the readiness banner in the chat overlay will warn you and suggest an alternative.

---

Validation status in the registry

The LLM Registry tree shows colored status indicators:

---

Tips

• Always test your connection after entering or changing an API key.
• Check the validation status in the registry tree for a quick overview of provider health.
• Error bubbles have action buttons that navigate directly to the relevant editor.
• The readiness banner updates automatically when you return from configuring a provider.

---