Troubleshooting

Start at the profile's connection test and diagnostic hint. Check the profile type, model, endpoint, local credential status, and request path before changing code.

Profile is not ready or connection test fails

1. In Tools > Beka Forge > AI Providers, confirm you selected the intended profile and that its provider type matches the service you are calling.
2. Check Base URL, the provider-specific endpoint, and the exact model name. A 404 commonly points to a base URL or endpoint mismatch; a model-not-found response usually means the selected model is unavailable to that account or local server.
3. For an API profile, re-enter the key in the masked local field, save, and test again. A 401/403 usually indicates a rejected key, missing permission, or incompatible authentication mode. Never paste the key into a shared asset or bug report.
4. Check Test connection and Check network separately. A successful network check does not prove the provider accepted the key, model, or request format.
5. For Custom JSON, compare the configured HTTP method, request body template, and response-text path with the endpoint's current API schema. The response path must point to the actual text field.

Credential is missing after moving or duplicating a profile

Credentials are scoped by project and provider asset GUID. Editing a profile keeps its identity; duplicating it creates a new GUID and a new local credential scope. Store the key again for the duplicate. On platforms where protected OS-backed credential storage is unavailable, the package reports that persistence cannot be used rather than saving plaintext.

429, quota, and server errors

• 429: check account quota and rate limits. The service honors a positive provider Retry-After interval without truncating it to 60 seconds; long waits remain cancellable. Retries cannot create quota.
• 5xx or timeout: verify the provider is reachable and try again after checking its status. Adjust timeout/retry settings only when the expected request duration warrants it.
• 400 or parse failure: inspect the request mode, model support, JSON mode, and Custom JSON response shape. Authentication and malformed-request failures are not treated as transient retry cases.

Runtime request stalls or cannot be cancelled

Do not call obsolete synchronous TrySendPrompt from gameplay code. Use BeginPromptCoroutine and retain its PromptCoroutineHandle; run handle.Coroutine on a live MonoBehaviour and call handle.Cancel() when the request owner is disabled. For asynchronous editor workflows, create a snapshot on the main thread and await SendPromptAsync.

Ollama connection or model errors

Confirm the Ollama service is running at the configured base URL and that the model has been pulled locally. Use Fetch Models to check model discovery, then copy the exact model identifier into the selected profile if it is not listed. Streaming uses Ollama NDJSON; check SupportsStreaming before exposing a streaming option.

Codex or Claude Code profile problems

These are editor-only subscription integrations, not API-key profiles. Install and sign into the corresponding native tool yourself, then use the profile's connection flow. Unity does not collect subscription credentials or reuse subscription tokens as API keys. Use an HTTP/API profile for player builds.

Documentation links offline

Documentation and Website buttons use the last valid cached URL registry, or bundled defaults if the registry cannot be fetched. The destination itself still needs an Internet connection. Registry requests do not contain provider keys, prompts, or project data.

Safe diagnostics

Use the provider window's sanitized diagnostics when reporting an issue. Remove prompts or response content that contains private project material, and confirm no API key, account token, or credential appears in the report or screenshot.