Languages: 🇺🇸 English | 🇧🇷 Português (Brasil) | 🇪🇸 Español | 🇫🇷 Français | 🇮🇹 Italiano | 🇷🇺 Русский | 🇨🇳 中文 (简体) | 🇩🇪 Deutsch | 🇮🇳 हिन्दी | 🇹🇭 ไทย | 🇺🇦 Українська | 🇸🇦 العربية | 🇯🇵 日本語 | 🇻🇳 Tiếng Việt | 🇧🇬 Български | 🇩🇰 Dansk | 🇫🇮 Suomi | 🇮🇱 עברית | 🇭🇺 Magyar | 🇮🇩 Bahasa Indonesia | 🇰🇷 한국어 | 🇲🇾 Bahasa Melayu | 🇳🇱 Nederlands | 🇳🇴 Norsk | 🇵🇹 Português (Portugal) | 🇷🇴 Română | 🇵🇱 Polski | 🇸🇰 Slovenčina | 🇸🇪 Svenska | 🇵🇭 Filipino | 🇨🇿 Čeština

---

	in (no hardcoded default)
	and
	and verify call log capture is enabled
	to override
	Node.js Compatibility below
/ (macOS)	— see macOS native module rebuild below
	Proxy Issues below

---

Cause: You are running a Node.js version outside OmniRoute's approved secure runtime floor. The most common case is running an older Node 20, 22, or 24 patch level that falls below the patched security floor OmniRoute requires.

Symptoms:

• or similar native binding errors
• orange warning banner with your Node version if the runtime is outside the supported secure policy

Fix:

nvm install 24 nvm use 24
1. should show or newer on the 24.x LTS line

Supported secure versions: , , or . Node.js 24.x LTS (Krypton) and Node.js 26 are fully supported.

/ "slice is not valid mach-o file"

Cause: After a global , the native binary inside the package may have been compiled for a different architecture or Node.js ABI than what is running locally. This is common on macOS (both Apple Silicon and Intel) when the pre-built binary does not match your environment.

Symptoms:

error

Fix — rebuild for your local environment (no Node.js downgrade required):

cd $(npm root -g)/omniroute/app
npm rebuild better-sqlite3
omniroute

Note: This recompiles the native binding against your local Node.js version and CPU architecture, resolving the binary mismatch. The officially supported range is , , or ( field in ). Node.js 24.x LTS (Krypton) and Node.js 26 are fully supported with v12.x.

---

Cause: The API key validation endpoint () was previously bypassing proxy configuration, causing failures in environments that require proxy routing.

Fix (v3.5.5+): This is now fixed. Provider validation routes through , honoring provider-level and global proxy settings automatically.

Cause: Background OAuth token refresh was not resolving proxy configuration per connection.

Fix (v3.5.5+): The token health check scheduler now resolves proxy config per connection before attempting refresh. Update to v3.5.5+.

Cause: On Node.js 22, the undici@8 dispatcher is incompatible with Node's built-in implementation.

Fix (v3.5.5+): OmniRoute now uses undici's own function when a proxy dispatcher is active, ensuring consistent behavior. Update to v3.5.5+.

---

Cause: Provider quota exhausted.

Fix:

Cause: Subscription quota exhausted.

Fix:

Cause: Kiro's backend enforces a single active session per OIDC client registration. When two accounts share the same registered client (connections imported before v3.8.0), refreshing one account's token invalidates the other's refresh token.

Fix (v3.8.0+): Re-import affected connections. Starting with v3.8.0, every new Kiro connection created via Import Token, Google/GitHub social login, or Auto-Import automatically registers its own dedicated OIDC client. The connection is therefore fully isolated and refreshing one account has no effect on any other account.

before v3.8.0 do not carry a per-connection client registration. Those connections continue to use the shared social-auth refresh endpoint. To gain isolation, delete the old connection from Dashboard → Providers and re-add it via any of the three import flows.

.

---

points to your running instance (e.g., )
1. points to your cloud endpoint (e.g., )
2. values aligned with server-side values

Returns 500

Symptom: on cloud endpoint for non-streaming calls.

Cause: Upstream returns SSE payload while client expects JSON.

Workaround: Use for cloud direct calls. Local runtime includes SSE→JSON fallback.

)
2. on cloud

---

1. (bundled CLIs)
2. and mount host bin directory as read-only
3. and : binary was found but failed healthcheck

curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
curl -s http://localhost:20128/api/cli-tools/claude-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'

---

---

in your file. Application logs are written under . Request artifacts are stored under when the call log pipeline is enabled in settings. When pipeline capture is enabled, set to omit stream chunk payloads, or tune to change the artifact cap in KB.

# Health dashboard
http://localhost:20128/dashboard/health

# API health check
curl http://localhost:20128/api/monitoring/health

(providers, combos, aliases, keys, settings)
• (, , ) + optional
• (when )
• when the call log pipeline is enabled

---

Fix:

Dashboard → Settings → Resilience
2. Reset All to clear all breakers, or wait for the cooldown to expire

Dashboard → Health → Provider Health for the failure pattern
1. Settings → Resilience → Provider Profiles and increase the failure threshold

---

or
• Dashboard → Providers

, , , , ,

---

Dashboard → Translator to debug format translation issues:

Playground
Chat Tester
Test Bench
Live Monitor

Thinking tags not appearing — Check if the target provider supports thinking and the thinking budget setting
• Tool calls dropping — Some format translations may strip unsupported fields; verify in Playground mode
• System prompt missing — Claude and Gemini handle system prompts differently; check translation output
• SDK returns raw string instead of object — Resolved in v1.x; response sanitizer strips non-standard fields (, , etc.) that cause OpenAI SDK Pydantic validation failures. If you still see this on v3.x+, please file an issue.
• GLM/ERNIE rejects role — Resolved in v1.x; role normalizer automatically merges system messages into user messages for incompatible models. If you still see this on v3.x+, please file an issue.
• role not recognized — Resolved in v1.x; automatically converted to for non-OpenAI providers. If you still see this on v3.x+, please file an issue.
• not working with Gemini — Resolved in v1.x; is now converted to Gemini's + . If you still see this on v3.x+, please file an issue.

---

• Settings → Resilience → Provider Profiles has auto-rate-limit enabled
• status codes or headers

Base delay — Initial wait time after first failure (default: 1s)
• Max delay — Maximum wait time cap (default: 30s)
• Multiplier — How much to increase delay per consecutive failure (default: 2x)

---

3. … ).

WFGY ProblemMap README

---

Symptoms:

Causes:

env var missing or empty
• misconfigured or pointing at a stale token

Fix:

and are set in
2. Dashboard → Providers → Windsurf → Reconnect

Symptoms:

Causes:

points to a path that does not exist

Fix:

1. (or the real path) in
2. Dashboard → CLI Tools

Symptoms:

Manual reset:

Dashboard: Settings → Model Cooldowns → click Re-enable on the affected card
• API: with management auth headers

Symptoms:

Cause: The OAuth flow did not complete (callback not received or token not persisted).

Fix:

from the CLI to re-trigger the OAuth flow, or
• Dashboard → Providers → Command Code → Reconnect

Symptoms:

Cause: ModelScope emits provider-specific headers. v3.8.0 ships dedicated handling for those headers, so older versions misread them as generic rate-limit hints.

Fix:

• toggle is enabled under Settings → Resilience

Symptoms:

Cause: The env var is missing from the production environment.

Fix:

1. in the production server env (and any client that talks to the bridge)

Symptoms:

• request returns a normal synchronous response instead of a background job handle

Cause: v3.8.0 intentionally degrades on the Responses API to synchronous execution while emitting a warning. Full async background execution is a future deliverable.

Fix:

, or

---

GitHub Issues: github.com/diegosouzapw/OmniRoute/issues
• Architecture: See for internal details
• API Reference: See for all endpoints
• Health Dashboard: Check Dashboard → Health for real-time system status
• Translator: Use Dashboard → Translator to debug format issues