Troubleshoot errors and collect diagnostics

1. 1

   Record scope and time

   Record the server origin, organization, affected user or API-key prefix, route, model or alias, exact local time, and timezone. Never record the full API key.

2. 2

   Check public process health

   Request GET /health on the same origin. HTTP 200 with {"status":"ok"} confirms the API process is answering; it does not prove the database, provider, catalog, license, or a specific model is healthy.

3. 3

   Capture the structured error

   Keep the HTTP status, response x-request-id header, error code or type, and error_id when present. Redact prompts, message content, tokens, credentials, and personal data.

4. 4

   Narrow the affected layer

   Check /ops, /provider-errors, /catalog-health, and /usage as your role permits. Reproduce once with the smallest safe request.

curl --fail-with-body --silent --show-error \
  "https://chat.example.com/health"

Native Orchestris routes use the native envelope below. Errors produced inside an authenticated OpenAI-compatible handler use the OpenAI-style envelope. Authentication, request-size, and rate-limit middleware can reject an /openai/v1 request before that handler runs, so a compatible client must safely handle either structured shape. Use the HTTP status together with structured fields; do not parse the human-readable message.

{
  "error": {
    "code": "quota_exceeded",
    "message": "Quota exceeded"
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "error_id": "0198..."
}

{
  "error": {
    "message": "Request limit exceeded.",
    "type": "too_many_requests"
  }
}

Retry-After is measured in seconds when present. Wait at least that long. For other transient 5xx failures, use bounded exponential backoff and preserve the same safe client correlation ID in your records.

1. 1

   Check the provider

   At /providers, confirm the organization provider is active and its credentials and endpoint verify successfully.

2. 2

   Check the organization model

   Confirm the model is present and active. Discovery alone does not grant access.

3. 3

   Check member access

   Organization and server administrators see the full organization catalog. A regular member needs an active group grant for the model.

4. 4

   Check the alias

   At /model-aliases, confirm the alias points to one active backing model. An alias is not an automatic fallback rule.

5. 5

   Check the API key

   For agent requests, confirm the key is active, unexpired, owned by the expected subject, and permits that model or alias.

Start with the logs your installation already produces. Capture the shortest window that includes the failure and its x-request-id, then redact it before sharing. Enable temporary debug logging only when the normal output is not enough.

Get-Content "$env:LOCALAPPDATA\Orchestris\logs\orchestris-api.stderr.log" -Tail 200
Get-Content "$env:LOCALAPPDATA\Orchestris\logs\orchestris-api.stdout.log" -Tail 200

sudo journalctl -u orchestris-api.service -u orchestris-admin.service --since "30 minutes ago" --no-pager

docker logs --since 30m orchestris-ce

If the normal logs do not explain the failure, temporarily set ORCHESTRIS_LOGGING__LEVEL to orchestris_api=debug,orchestris_core=debug,orchestris_providers=debug. On Windows, edit %LOCALAPPDATA%\Orchestris\orchestris.env and choose Restart Server from the tray. On macOS, edit ~/Library/Application Support/Orchestris/orchestris.env and choose Restart from the Orchestris menu. On Linux, add the override to /etc/orchestris/orchestris.env.local and restart orchestris.target. For Docker, stop and remove only the orchestris-ce container, then repeat the Docker guide's Run Community Edition command with the extra environment option below. The named orchestris-data volume keeps the deployment state.

ORCHESTRIS_LOGGING__LEVEL=orchestris_api=debug,orchestris_core=debug,orchestris_providers=debug

-e ORCHESTRIS_LOGGING__LEVEL="orchestris_api=debug,orchestris_core=debug,orchestris_providers=debug" \

sudo systemctl restart orchestris.target

ORCHESTRIS_LOGGING__LEVEL=info

• Recreate the Community Edition container safelyReuse the pinned image, public URL, ports, and orchestris-data volume from the documented Docker run command.

• Orchestris Chat version and platform, or Server version/deployment method
• Server origin without credentials, affected organization, and affected role
• Exact timestamp with timezone and whether the issue is repeatable
• HTTP method and route, status, structured error code or type, x-request-id, and error_id
• Model or alias identifier and only the API-key prefix when an agent request is involved
• A minimal reproduction and a short, redacted log window around the same request ID

• Contact Orchestris SupportUse the support channel after collecting the safe evidence above.
• Review usage and operational healthInspect provider, catalog, usage, and system views.