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) is 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) is 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:

---

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 — Fixed in v1.1.0: response sanitizer now strips non-standard fields (, , etc.) that cause OpenAI SDK Pydantic validation failures
• GLM/ERNIE rejects role — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models
• role not recognized — Fixed in v1.1.0: automatically converted to for non-OpenAI providers
• not working with Gemini — Fixed in v1.1.0: is now converted to Gemini's +

---

• 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

---

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