Troubleshooting

Troubleshoot Nexus from the bottom up: Runtime, authentication, provider/runtime health, model catalog, then gateway routing.

Runtime is offline

Check:

• The app is pointing at the expected Runtime URL.
• Runtime is running on the local machine or selected controller.
• The configured port is not already in use.
• The app token is still present in Keychain.

Use Repair connection for local Runtime issues. For remote controller profiles, confirm the controller URL and token instead of repairing the local Runtime.

Token rejected

Symptoms:

• UNAUTHORIZED
• app reports missing token
• gateway client receives authentication errors

Fix:

1. Create a fresh client token in Settings > Client Tokens.
2. Update the client app's API key.
3. Confirm the client is sending one accepted token header.
4. Revoke old tokens after clients have moved.

Remember that provider API keys are not Nexus API keys. Clients authenticate to Nexus with a local Nexus token.

Provider test fails

Check:

• Provider is enabled.
• Credential is configured when required.
• Base URL is correct.
• The provider account can list models.
• The provider supports the endpoint family you plan to use.

Provider diagnostics return stable statuses such as missing_credential, invalid_configuration, rejected, unreachable, or invalid_response.

No models appear

Check the setup path:

• For online providers, sync models or enable automatic provider models.
• For local runtimes, install/start the runtime and run model sync.
• For search/install flows, confirm a compatible Nexus-managed runtime is installed.
• For hidden models, switch the visibility filter in Models.
• For disabled providers, re-enable the provider.
• For discovered local AI, rescan after the runtime is reachable; onboarding providers should not be the only scanned providers shown.

If model storage looks inconsistent, run Library health from Models.

Gateway request fails

Common causes:

• Missing local Nexus token
• Incorrect base URL
• Model ID typo
• Hidden model
• Disabled provider
• Endpoint family mismatch
• Provider credential missing
• Local runtime stopped
• Route pack fallback unavailable
• Multipart route using a preset or route pack instead of a direct model ID or alias

If the error is MODEL_ENDPOINT_NOT_SUPPORTED, choose a route supported by that model or update the model's endpoint families.

For image, speech, transcription, or rerank failures, confirm the selected model advertises openai.images, openai.audio_speech, openai.audio_transcriptions, or rerank.documents.

Browser client fails

Separate CORS from authentication:

• If the browser blocks before the request reaches Nexus, update CORS origins.
• If Nexus returns UNAUTHORIZED, fix the local Nexus token.
• If another device cannot reach Runtime, enable network exposure and restart Runtime.

CORS alone does not expose Runtime to the LAN.

Runtime action fails

Check:

• Runtime is supported on this host.
• Runtime is enabled.
• Another job is not already targeting the same runtime.
• The port is free.
• The executable exists for path-based installs.
• The runtime is stopped before update when required.

Nexus controls only processes it starts. If a runtime was started outside Nexus, stop it manually before using Nexus lifecycle actions.

Model action fails

Check:

• Runtime is installed and reachable.
• Model action is supported by that runtime.
• Search result has an install action.
• GGUF import selected a valid .gguf file.
• The model is not still referenced by a preset or route pack.
• No active model job targets the same runtime.

For llama.cpp deletes, Nexus removes only Nexus-managed relative GGUF files. Unmanaged local paths are intentionally rejected.

Preset warnings appear

Preset warnings mean Nexus saved or validated a setting that the current target model may not support.

Common codes:

• unsupported_param: the provider does not advertise a saved parameter.
• unsupported_thinking: the model/provider cannot use thinking controls.
• unsupported_thinking_display: the provider cannot produce the requested reasoning display behavior.
• unsupported_prompt_cache: prompt caching is not supported for that target.
• unknown_provider_bucket: provider options include a bucket that does not match a known provider kind.

Fix by changing the preset target model, removing unsupported fields, or keeping the warning if the preset intentionally carries settings for a future model/provider.

GPU placement needs attention

Warnings:

• GPU_FALLBACK_TO_CPU: the runtime used system memory instead of the planned GPU placement.
• GPU_PLACEMENT_VERIFICATION_LIMITED: the model loaded, but Runtime could not fully prove effective GPU placement.

Actions:

1. Refresh hardware.
2. Review GPU & Performance for the model.
3. Preview the plan.
4. Apply and verify again.
5. Roll back if the active setup is worse.

Use CPU-only only when that is the intended behavior.

Gauge shows no data

Check:

• Gauge is enabled in Settings.
• The source account is connected and enabled.
• Reporting credential is valid.
• Refresh has completed.
• The selected date range has data.
• The provider actually exposes the metric you expect.

Gauge distinguishes local account reachability from provider status-page health.

Collect support-safe diagnostics

Use Settings > Diagnostics.

Do not paste provider keys, local Nexus token values, token prefixes, local paths, prompts, responses, raw request bodies, provider output, command lines, process IDs, or raw upstream errors into support tickets.