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).

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.

"Request timed out"

Cause: The provider took too long to respond (over 2 minutes).

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.