Troubleshooting (Hausa)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

Ga Masu Amfani: Kuna neman gyare-gyare masu sauri? Duba Takaitaccen Bayani da ke ƙasa.

Matsalolin da aka fi samu da hanyoyin magance su na OmniRoute.

Bayani Cikin Sauri

Sabon mai amfani da OmniRoute ne? Fara daga nan — waɗannan suna warware matsaloli 90%:

Abin da nake gani	Abin da yake nufi	Abin da za a yi
"Ba za a iya haɗawa ba"	OmniRoute ba ya aiki	Gudanar da `omniroute` ko `docker restart omniroute`
"Maɓallin API ba daidai ba"	Maɓallinka ba daidai ba ne ko ya ƙare	Sake kwafe maɓallin daga gidan yanar gizon mai bayarwa
"An wuce iyakar buƙatu"	Kana aika buƙatu da yawa	Jira minti 1, ko amfani da `model: "auto"` don sauyawa ta atomatik
"An wuce ƙayyadadden kaso"	Ka ƙare kaso na kyauta/na biya	Haɗa ƙarin masu bayarwa, ko amfani da masu bayarwa na kyauta (Kiro, Pollinations)
"Amsoshi suna jinkiri"	Mai bayarwa yana da cunkoso ko yana da nisa	Yi amfani da `model: "auto/fast"` ko haɗa mai bayarwa mafi sauri (Groq, Cerebras)
"An yi amfani da mai bayarwa marar dacewa"	`auto` ya zaɓi wani mai bayarwa	Wannan al'ada ce! `auto` yana zaɓar mafi dacewa. Tilasta takamaiman mai bayarwa da `model: "openai/gpt-4o"`
"502 Ƙofar Sadarwa Mara Kyau"	Mai bayarwa ba ya aiki	Jira sannan ka sake gwadawa, ko amfani da `model: "auto"` don sauya masu bayarwa
"401 Ba a Ba da Izini ba"	Bayanan shaidarka ba daidai ba ne	Duba maɓallin API ɗinka ko sake tabbatar da izini ta OAuth
"ba a gane omniroute ba"	Windows PATH ba ya ɗauke da global node modules	Ƙara npm global prefix ɗinka zuwa Windows PATH. Nemo shi da `npm config get prefix`.
"429 Buƙatu Sun Yi Yawa"	An taƙaita yawan buƙatu	Jira minti 1, ko haɗa ƙarin masu bayarwa

Har yanzu kana fuskantar matsala? Duba cikakken jagorar warware matsala da ke ƙasa, ko yi tambaya a Discord.

Cikakken Jagorar Warware Matsala

Taƙaita Yawan Buƙatu a Masu Bayarwa na Kyauta (429 / 400 / 401)

Alama: Lokacin amfani da model: "auto" tare da masu bayarwa na kyauta/marasa buƙatar tantancewa (opencode, auggie, da sauransu), lokaci-lokaci kana samun HTTP 429, 400, ko 401 maimakon amsoshi. Buƙatun suna nasara idan aka sake gwada wannan saƙon bayan ɗan lokaci, amma sarrafa aiki ta atomatik (cron jobs, agents, scripts) yana katsewa a gazawar farko.

Asalin matsalar: Hanyoyin gazawa guda uku masu zaman kansu suna taruwa:

Iyakar yawan buƙatun mai bayarwa (429): Matakan kyauta na iya tilasta ƙayyadadden kaso a kowane zangon lokaci. Aika tarin kiraye-kiraye a lokaci guda yana ƙare shi, don haka za a ƙi buƙata ta gaba har sai zangon ya sake farawa.
Samfuri mara aiki a passthrough (400/401): Tarin auto/* na iya ƙunsar samfuran passthrough daga opencode waɗanda aka yi wa rajista a kundin bayanai amma ba su da ingantattun bayanan shaida masu aiki (misali oc/north-mini-code-free → 401). Auto-router yana gwada ɗaya, ya gaza, sannan kuskuren ya wuce kafin sauyawa ta fara aiki.
Ƙaruwar tasirin aiki a lokaci guda (429 a ƙarƙashin nauyi): Lokacin da zaman agent/cron da yawa suka aika buƙatu zuwa auto a lokaci guda, jimillar yawan buƙatun tana wuce abin da masu bayarwa na kyauta za su iya jurewa, don haka ana ɗaukar ingantattun kiraye-kiraye a matsayin amfani mara kyau.

Tabbataccen gyara (al'umma ta bayar da rahoto, 2026-08-10): daidaita environment variables guda uku domin juyawa, aiki a lokaci guda, da sauyawa su shawo kan rashin daidaiton matakin kyauta maimakon tsarin ya tsaya saboda shi:

export OMNIROUTE_ROTATE_ON_400=true           # matsa zuwa wani samfuri/mai bayarwa idan an sami 400/401 (yana tsallake samfuran passthrough marasa aiki)
export OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT=4   # bayyanannen iyakar karɓar manyan ayyuka (ba a saita shi ta tsohuwa ba: babu iyakar adadin buƙatu, duba bayanin da ke ƙasa)
export OMNIROUTE_CHAT_ADMISSION_QUEUE_MS=5000 # jira mai iyaka na tsawon lokaci domin samun ƙarfin manyan ayyuka maimakon 503 mai ba da damar sake gwadawa nan take

Saita waɗannan a cikin muhallin aikin OmniRoute (daemon ɗin, misali ta LaunchAgent plist ko systemctl edit), sannan sake kunna OmniRoute. Alamar juyawa ita ce hanya guda mafi tasiri: tana sauya gazawa kai tsaye zuwa sake gwadawa ba tare da mai amfani ya lura ba, ta amfani da ingantaccen mai bayarwa a cikin tarin.

Lura: OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT yana iyakance adadin manyan buƙatu — masu dogon mahalli — da za su gudana a lokaci guda; wannan iyaka ƙofar karɓa ce, ba mai taƙaita yawan buƙatun mai bayarwa ba. Sabuntawar #503-fanout: ba a ƙara saita wannan var ta tsohuwa ba (yanzu yana aiki ne kawai idan an saita shi a bayyane, kamar yadda aka yi a sama) — maimakon haka, ana sarrafa karɓar manyan ayyuka ta kasafin bytes da aka samar ta atomatik (OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES), wanda yake daidaita kansa bisa ainihin iyakar ƙwaƙwalwar na'urar, don haka sabon deployment ya kamata ya ga raguwar ƙin buƙatu na 503 chat_admission_busy sosai ba tare da saita wannan var kwata-kwata ba; saita shi a bayyane a nan har yanzu yana aiki daidai kamar yadda aka bayyana. Bayyanannun sauye-sauyen kasafin bytes ana taƙaita su zuwa 8 MiB–2 GiB. 413 body_exceeds_budget ba matsala ce ta ɗan lokaci ba: ƙara wannan kasafin bytes, rage OMNIROUTE_CHAT_HARD_MAX_BODY_BYTES, ko ƙara iyakar ƙwaƙwalwar aikin. Watsar da buƙata saboda inflight_bytes_budget cunkoso ne na ɗan lokaci kuma har yanzu ana iya sake gwadawa. Ana sarrafa iyakar yawan buƙatu ta kowane mai bayarwa (open-sse/services/rateLimitManager.ts) daban ta RATE_LIMIT_MAX_WAIT_MS, RATE_LIMIT_MAX_QUEUE_DEPTH, da RATE_LIMIT_AUTO_ENABLE — duba .env.example.

Yadda za a tabbatar ya yi aiki: gudanar da agent/cron ɗinka sau biyu a jere cikin sauri, sannan ka tabbatar dukansu sun yi nasara. Kafin gyaran, gudu na biyu yawanci yana jefa kuskuren 429/401. Bayan gyaran, za a sake gwada buƙatun da suka gaza (idan akwai) ta atomatik ba tare da an nuna maka ba, kuma kiran zai kammala. Haka kuma, za ka iya yin curl /monitoring/health sannan ka lura da filin rateLimitedUntil a haɗin masu samarwa da kuma circuitBreakers.providerBreakers[].state na masu samarwar da abin ya shafa — matsayin zai kasance ɗaya daga cikin CLOSED, DEGRADED, OPEN, ko HALF_OPEN (duba src/shared/utils/circuitBreaker.ts), kuma mai samarwar da ke ci gaba da gazawa zai sauya daga CLOSED → DEGRADED → OPEN kafin lokacin sake saiti ya ba da damar aika buƙatar gwaji (HALF_OPEN).

Idan har yanzu kana ganin 429: asusun da ke aiki na wannan mai samarwar ya ƙare da gaske da quota ɗinsa (ba wai iyakar saurin buƙatu kawai ba). Ƙara asusu na biyu don mai samarwar iri ɗaya a OmniRoute dashboard → Providers → Accounts, ko haɗa wani mai samarwa na kyauta (misali, routeway, auggie). Juyawa tsakanin asusu yana taimakawa ne kawai ga matsalolin wucin gadi na iyakar saurin buƙatu/400/401; ƙarewar quota gaba ɗaya na buƙatar bayanan shiga na biyu ko wani mai samarwa daban.

Idan kana ganin 403 a kan samfuran vision (auto/vision, bazaarlink/*): asusun da aka haɗa ba shi da shirin biyan kuɗi wanda ya ƙunshi vision, ko kuma API key ɗin ba shi da isassun izini. Tabbatar a dashboard na mai samarwar cewa key scope ɗin ya ƙunshi vision/multimodal, ko kuma haɗa asusun matakin biyan kuɗi sannan ka bar shi a matsayin maƙasudin vision.

Gargaɗin npm install (ERESOLVE / peer / deprecated)

Lokacin da ka gudanar da npm install -g omniroute, za ka iya ganin tarin gargaɗi kamar npm warn ERESOLVE, sanarwar peer-dependency, da saƙonnin deprecated. Ana tsammanin waɗannan kuma ba sa haifar da wata matsala. Shigarwar ta yi nasara idan ka ga added <N> packages a cikin sakamakon.

Don ɓoye gargaɗin warware peer-dependency, yi amfani da tsarin shigarwa da OmniRoute ke goyon baya:

npm install -g omniroute --legacy-peer-deps

--legacy-peer-deps yana ɓoye ERESOLVE da sanarwar peer-dependency kawai. Sanarwar daina tallafawa za ta ci gaba da bayyana saboda tana fitowa ne daga fakitin wasu ɓangarori da aka gada; ba ta nuna cewa shigarwar ta gaza ba.

Gargaɗin yana fitowa ne daga tsofaffin iyakokin peer-dependency a cikin fakitin wasu ɓangarori waɗanda OmniRoute ba ya sarrafawa:

marked-terminal yana buƙatar marked >=1 <16, amma an samu marked@18 — yana aiki lafiya a aikace; iyakar peer ta upstream ce kawai ta tsufa.
deprecated prebuild-install@7.1.3 — mataimaki ne na ɗauko native-binary da aka gada. Ba a amfani da shi wajen shigar da transport binding na wreq-js da aka ƙayyade, kuma ba ya nuna cewa saitin transport na mai samar da web-cookie ya gaza.

Ba a buƙatar wani mataki — ba za a iya ɓoye gargaɗin gaba ɗaya ba sai an yi fork na fakitin upstream.

Gemini Web da Playwright Chromium

Idan buƙatar Gemini Web ta dawo da 503 tare da saƙon cewa ba a shigar da Playwright Chromium ba, fakitin npm yana nan amma binary na burauzar ne ya ɓace. Playwright da gangan yana ware sauke burauza daga shigar da fakitin npm, saboda haka ana tsammanin wannan martani har sai an shigar da burauzar.

Don shigarwar npm ta global, shigar da Chromium daga kundin adireshin fakitin OmniRoute domin cache na burauzar ya kasance mallakin shigarwar Playwright ɗin nan:

cd "$(npm root -g)/omniroute"
npx playwright install chromium

Sake kunna OmniRoute bayan shigarwar, sannan ka sake gwada buƙatar Gemini Web. Idan kana gudanar da OmniRoute daga Docker image, yi amfani da image na -web (ko build target na runner-web), wanda ya ƙunshi Chromium da dependencies ɗinsa; base image ba ya ƙunshe da su.

Gyare-gyare Masu Sauri

Matsala	Mafita
Shiga na farko ba ya aiki	Saita `INITIAL_PASSWORD` a cikin `.env` (babu hardcoded default)
Dashboard yana buɗewa a port ɗin da ba daidai ba	Saita `PORT=20128` da `NEXT_PUBLIC_BASE_URL=http://localhost:20128`
Ba a rubuta logs zuwa disk	Saita `APP_LOG_TO_FILE=true` sannan ka tabbatar an kunna ɗaukar call log
EACCES: an hana izini	Saita `DATA_DIR=/path/to/writable/dir` don maye gurbin `~/.omniroute`
Ba a adana tsarin routing	Sabunta zuwa sabuwar sakin v3.x (an riga an haɗa gyaran Zod schema na dorewar settings a sigogin baya)
Faɗuwar shafin shiga / shafi mara komai	Duba sigar Node.js — duba Dacewar Node.js a ƙasa
`dlopen` / `slice is not valid mach-o file` (macOS)	Gudanar da `cd $(npm root -g)/omniroute/app && npm rebuild better-sqlite3 && omniroute` — duba sake gina native module na macOS a ƙasa
Proxy "fetch failed"	Tabbatar an saita proxy config a matakin da ya dace — duba Matsalolin Proxy a ƙasa
Docker `curl: (56) Recv failure: Connection reset by peer`	Wataƙila port bind na Docker yana sauka a kan IPv6. Yi amfani da `-p 127.0.0.1:20128:20128` don tilasta IPv4, ko gwada da `curl -4`. Duba Docker IPv6 a ƙasa
Antivirus yana killace `README.md`	False positive ne — duba False positives na antivirus a ƙasa
Kaspersky yana ayyana manhajar Desktop a matsayin Trojan	Behavioral false positive ne a kan installer marar sa hannu — duba False positives na antivirus a ƙasa

Gargaɗin Ƙarya na Antivirus

Avast/AVG yana keɓe `README.md` da `MD:HttpRequest-inf[Susp]`

Wannan gargaɗin ƙarya ne. Babu wani abu da ya kamu, kuma ba a buƙatar ɗaukar wani mataki.

Avast da AVG suna amfani da hanyar tantancewa ta heuristic wadda ke yi wa fayilolin rubutu na yau da kullum/Markdown da ke ɗauke da hanyoyin haɗi masu yawa masu kama da buƙatun HTTP alama. Ana haɗa README.md na OmniRoute a cikin kunshin npm (an jera shi a package.json → files), don haka yana sauka a node_modules/omniroute/README.md yayin shigarwa ta global — kuma yana ɗauke da misalai kusan 15 na http://localhost:20128/... (endpoints na MCP HTTP/SSE, URL na A2A .well-known, da gutsattsarin curl). Yawan waɗannan hanyoyin haɗin ya isa ya kunna wannan tantancewar.

Idan wannan ya fara faruwa kwanan nan kawai: nau'in fayil ɗin bai canza ba. README ya ƙara faɗaɗa teburin endpoints ɗinsa (an ƙara MCP HTTP + SSE + A2A) da ƙarin misalan curl, wanda ya sa ya wuce iyakar tantancewar.

Fayil ɗin takardu ne marar aiki wanda ba ya ɗauke da wani abun da za a iya aiwatarwa. Za ku iya dawo da shi daga keɓewa cikin aminci.

Abin da za a yi:

Dakatar da sanarwar — ware kundin shigarwar daga binciken antivirus ɗinku (Avast: Settings → Exceptions), ta ƙara hanyar node_modules ta global da/ko kundin bayanan OmniRoute (~/.omniroute/).
Kai rahoton gargaɗin ƙarya — https://www.avast.com/false-positive-file-form.php, tare da haɗa README.md da aka keɓe. Wannan shi ne gyaran da zai taimaki kowa, domin heuristic na mai samar da antivirus ne ke yin tsauraran hukunci fiye da kima kan fayil ɗin rubutu.

Dalilin da ya sa ba ma “gyara” wannan daga ɓangarenmu: duk misalan http://localhost ne, kuma localhost ba zai iya zama https ba sai an fuskanci matsalolin takardar shaida da aka sanya wa hannu da kai. Gurɓata takardun domin kauce wa heuristic na kamfani ɗaya zai cutar da kowane mai karatu don kawai a biya bukatar wata matsalar na'urar bincike.

Kaspersky yana yi wa manhajar Desktop alama da `PDM:Trojan.Win32.Generic`

Wannan gargaɗin ƙarya ne daga heuristic na halayya. Babu wani abu da ya kamu. Farkon PDM: na Kaspersky yana nufin hukuncin ya fito ne daga Proactive Defense Module (System Watcher), wanda ke tantance abin da mai shigarwar yake yi maimakon kwatanta shi da sanannun malware. Idan ya kunna, Kaspersky yana “mayar da baya” gaba ɗaya shigarwar — yana share fayilolin da ya riga ya rubuta — don haka manhajar takan lalace ko ta ɓace.

Fayilolin da yake yi wa alama sassa ne na yau da kullum daga sanannun dependencies masu buɗaɗɗen tushe da aka haɗa da manhajar desktop, misali:

resources/app/.build/next/node_modules/playwright-<hash>/lib/…/agentParser.js da workerProcessEntry.js — Playwright, library na sarrafa burauza ta atomatik da ake amfani da shi don shiga ga masu samar da sabis daga cikin manhajar da kuma tattaunawa mai dogaro da burauza.
resources/app/.build/next/node_modules/@wreq-js/binding-win32-<arch>-msvc-<hash>/wreq-js.win32-<arch>-msvc.node — native binding na wreq-js da aka ƙayyade sigarsa, wanda ake amfani da shi don HTTP mai kwaikwayon sawun burauza kan masu samar da sabis masu amfani da web-cookie (<arch> shi ne x64 ko arm64).

Dalilin da ya sa yake kunna: mai shigarwa na Windows ba a riga an sanya masa hannu ta lamba ba, don haka mai shigarwar NSIS marar sa hannu ba shi da wani suna na amincewa, kuma heuristics na halayya suna aiki da tsananin da ya kai kololuwa. Idan aka haɗa wannan da native DLL da kuma ɗaruruwan fayilolin .js da ake rubutawa ƙarƙashin %LOCALAPPDATA%\Programs\OmniRoute (ciki har da kundin kunshe-kunshe masu ƙarin hash daga standalone build na Next.js), hakan ya isa ya kunna heuristic ɗin. An shirya sanya hannu ta lamba; har sai an aiwatar da shi, sabbin releases na iya maimaita wannan.

Abin da za a yi:

Da farko ku tabbatar da ingancin abin da kuka sauke (wannan yana kawar da yiwuwar an yi wa fayil ɗin kutse). Kowane release yana wallafa latest.yml, wanda filin sha512 nasa (base64) ke rufe mai shigarwar OmniRoute.Setup.<version>.exe. A PowerShell, daga babban fayil ɗin da ke ɗauke da mai shigarwar:
```
$b = [System.Security.Cryptography.SHA512]::Create().ComputeHash(
  [System.IO.File]::ReadAllBytes("$PWD\OmniRoute.Setup.<version>.exe"))
[Convert]::ToBase64String($b)
```
Dole ne sakamakon ya yi daidai da latest.yml → sha512. Idan bai yi daidai ba, ku share fayil ɗin sannan ku sake sauke shi kawai daga shafin releases na GitHub.
Dawo da su + ware su — dawo da abubuwan da aka mayar da baya daga keɓewa sannan ku ƙara keɓancewa ga %LOCALAPPDATA%\Programs\OmniRoute (Kaspersky → Settings → Threats and Exclusions), sannan ku sake shigarwa.
Kai rahoton gargaɗin ƙarya — https://opentip.kaspersky.com/. Rahotannin FP da masu amfani suka aika suna taimakawa sosai wajen hanzarta saka shi cikin jerin abubuwan da aka amince da su.

Daidaituwar Node.js

Shafin shiga yana rushewa ko yana nuna kuskuren "Module self-registration"

Dalili: Kana amfani da sigar Node.js da ba ta cikin mafi ƙarancin amintaccen yanayin aiki da OmniRoute ya amince da shi. Mafi yawan abin da ke faruwa shi ne amfani da tsohuwar sigar gyaran Node 22 ko 24 wadda take ƙasa da mafi ƙarancin matakin tsaro da OmniRoute ke buƙata.

Alamomi:

Shafin shiga yana nuna farin allo ko kuskuren uwar garke
Console yana nuna Error: Module did not self-register ko makamantan kurakuran native binding
Shafin shiga yana nuna tutar gargaɗi mai launin lemu tare da sigar Node ɗinka idan yanayin aikin yana wajen ƙa'idar tsaro da ake tallafawa

Gyara:

Shigar da sigar Node.js LTS da ake tallafawa (shawara: Node.js 24.x):
```
nvm install 24
nvm use 24
```
Tabbatar da sigarka: node --version ya kamata ya nuna v24.0.0 ko mafi sabo a layin 24.x LTS
Sake shigar da OmniRoute: npm install -g omniroute
Sake farawa: omniroute

Amintattun sigogin da ake tallafawa: >=22.22.2 <23 ko >=24.0.0 <27. Node.js 24.x LTS (Krypton) da Node.js 26 suna samun cikakken tallafi.

npm v11+: Ba a shigar da `better-sqlite3` ba (Cannot find module)

Dalili: npm v11 (wanda yake zuwa tare da Node.js 24+) yana toshe scripts na shigarwa don optional dependencies ta tsoho. Saboda an jera better-sqlite3 a cikin optionalDependencies kuma yana buƙatar native compilation (node-gyp rebuild), npm yana tsallake shi ba tare da sanarwa ba.

Alamomi:

Uwar garke tana rushewa yayin farawa tare da Cannot find module 'better-sqlite3'
ls node_modules/better-sqlite3 yana nuna "No such file or directory"
npm ls better-sqlite3 yana nuna (empty)

Gyara:

Amince da scripts na shigarwa sannan ka sake shigarwa:
```
npm approve-scripts better-sqlite3
npm install
```

Ko shigar da prebuilt ɗin da hannu:

npm pack better-sqlite3@13.0.1
tar -xzf better-sqlite3-*.tgz -C node_modules
mv node_modules/package node_modules/better-sqlite3
rm better-sqlite3-*.tgz

Tabbatar yana aiki: node -e "require('better-sqlite3')(':memory:').close(); console.log('OK')"

macOS: `dlopen` / "slice is not valid mach-o file"

Dalili: Bayan yin npm install -g omniroute na gama-gari, wataƙila an compile native binary na better-sqlite3 da ke cikin package ɗin don wani architecture ko Node.js ABI daban da wanda yake aiki a na'urar. Wannan ya zama ruwan dare a macOS (Apple Silicon da Intel) idan pre-built binary bai dace da yanayinka ba.

Alamomi:

Uwar garke tana kasa farawa nan take tare da kuskuren dlopen
Kuskuren yana ɗauke da slice is not valid mach-o file
Cikakken misali:

dlopen(/Users/<user>/.nvm/versions/node/v24.14.1/lib/node_modules/omniroute/app/node_modules/better-sqlite3/build/Release/better_sqlite3.node, 0x0001): tried: '...' (slice is not valid mach-o file)

Gyara — sake ginawa don yanayin na'urarka (ba a buƙatar komawa tsohuwar sigar Node.js):

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

Lura: Wannan yana sake compile native binding ɗin bisa sigar Node.js da CPU architecture na na'urarka, yana warware rashin daidaituwar binary. Matsakaicin yanayin aikin da ake tallafawa a hukumance shi ne >=22.22.2 <23 ko >=24.0.0 <27 (SUPPORTED_NODE_RANGE a cikin src/shared/utils/nodeRuntimeSupport.ts, wanda ya yi daidai da filin engines na package.json). Node.js 24.x LTS (Krypton) da Node.js 26 suna samun cikakken tallafi tare da better-sqlite3 v12.x.

Matsalolin Proxy

Tabbatar da mai bayarwa yana nuna "fetch failed"

Dalili: A baya, maƙurar tabbatar da maɓallin API (POST /api/providers/validate) tana tsallake saitin proxy, wanda ke haifar da gazawa a muhallan da ke buƙatar tura zirga-zirga ta proxy.

Gyara (v3.5.5+): Yanzu an gyara wannan. Hanyoyin tabbatar da mai bayarwa suna bi ta runWithProxyContext, tare da mutunta saitunan proxy na matakin mai bayarwa da na gama-gari ta atomatik.

Binciken lafiyar token yana gazawa da "fetch failed"

Dalili: Sabunta token na OAuth da ke gudana a bayan fage ba ya tantance saitin proxy na kowace haɗi.

Gyara (v3.5.5+): Yanzu mai tsara binciken lafiyar token yana tantance saitin proxy na kowace haɗi kafin yunƙurin sabuntawa. Sabunta zuwa v3.5.5+.

Proxy na SOCKS5 yana mayar da "invalid onRequestStart method"

Dalili: A Node.js 22, dispatcher na undici@8 bai dace da ginannen aiwatarwar fetch() na Node ba.

Gyara (v3.5.5+): Yanzu OmniRoute yana amfani da aikin fetch() na undici kansa lokacin da dispatcher na proxy ke aiki, domin tabbatar da daidaitaccen aiki. Sabunta zuwa v3.5.5+.

Proxy na MITM a ƙarƙashin WSL: ba a katse manhajojin tebur a kan Windows host

Dalili: Ana shigar da proxy na MITM da takardar shaidar CA ɗinsa a cikin muhallin da OmniRoute ke aiki. A ƙarƙashin WSL, wannan muhalli shi ne Linux guest, yayin da manhajojin AI na tebur (Kiro, Trae, Copilot, Zed, …) ke aiki a kan Windows host. Manhajojin host ba sa amincewa da ma'ajiyar takardun shaida ta guest kuma ba sa tura zirga-zirgarsu ta proxy na tsarin guest, saboda haka katse zirga-zirgar manhajojin tebur ba ya aiki a can.

Shawara: Gudanar da OmniRoute kai tsaye a kan OS ɗaya da manhajojin tebur da kake son katse zirga-zirgarsu (Windows don manhajojin Windows; haka nan ga macOS/Linux). Barin OmniRoute a cikin WSL yayin niyyar manhajojin host yana buƙatar amincewa da takardar shaidar CA da aka samar da hannu a kan Windows host, sannan a nuna saitunan cibiyar sadarwa/proxy na kowace manhajar host zuwa maƙurar proxy ta WSL — wannan tsari ne marar tallafi kuma mai sauƙin lalacewa.

Matsalolin Masu Bayarwa

"Language model did not provide messages"

Dalili: Ƙimar amfani ta mai bayarwa ta ƙare.

Gyara:

Duba mai bin diddigin ƙimar amfani a dashboard
Yi amfani da haɗin da ke da matakan madadin
Sauya zuwa mataki mai rahusa/kyauta

Iyakance Adadin Buƙatu

Dalili: Ƙimar amfani ta rajista ta ƙare.

Gyara:

Ƙara madadin: cc/claude-opus-4-6 → glm/glm-4.7 → if/qwen3.8-max-preview
Yi amfani da GLM/MiniMax a matsayin madadin mai rahusa

Token na OAuth Ya Ƙare

OmniRoute yana sabunta token ta atomatik. Idan matsalolin suka ci gaba:

Dashboard → Mai Bayarwa → Sake Haɗawa
Share haɗin mai bayarwa sannan a sake ƙara shi

Asusun Kiro da yawa: asusu na biyu yana mayar da na farko mara inganci

Dalili: Backend na Kiro yana tilasta zama mai aiki guda ɗaya ga kowace rijistar OIDC client. Lokacin da asusu biyu suke amfani da registered client ɗaya (haɗe-haɗen da aka shigo da su kafin v3.8.0), sabunta token na asusu ɗaya yana mayar da refresh token na ɗayan mara inganci.

Gyara (v3.8.0+): Sake shigo da haɗe-haɗen da abin ya shafa. Tun daga v3.8.0, kowane sabon haɗin Kiro da aka ƙirƙira ta Shigo da Token, shiga ta zamantakewa ta Google/GitHub, ko Shigo da Kai Tsaye yana rijistar nasa keɓaɓɓen OIDC client ta atomatik. Saboda haka, haɗin yana kasancewa cikakken keɓantacce, kuma sabunta wani asusu ba ya yin tasiri ga wani asusu.

Haɗe-haɗen da aka shigo da su kafin v3.8.0 ba su ƙunshe da rijistar client ta kowace haɗi. Waɗannan haɗe-haɗen suna ci gaba da amfani da shared social-auth refresh endpoint. Don samun keɓancewa, share tsohon haɗin daga Dashboard → Masu Bayarwa sannan a sake ƙara shi ta ɗaya daga cikin hanyoyin shigo da bayanai guda uku.

Don cikakkun bayanai da umarnin mataki-mataki na ƙara asusun Kiro biyu tare, duba docs/guides/KIRO_SETUP.md.

Matsalolin Cloud

Kurakuran Aiki Tare na Cloud

Tabbatar cewa BASE_URL yana nuni zuwa instance ɗinka da ke aiki (misali, http://localhost:20128)
Tabbatar cewa CLOUD_URL yana nuni zuwa endpoint na cloud ɗinka (misali, https://omniroute.dev)
Ka tabbatar ƙimomin NEXT_PUBLIC_* sun yi daidai da ƙimomin gefen server

`stream=false` na Cloud Yana Mayar da 500

Alama: Unexpected token 'd'... a endpoint na cloud don kiraye-kirayen da ba na streaming ba.

Dalili: Upstream yana mayar da payload na SSE alhali client yana tsammanin JSON.

Mafita ta wucin gadi: Yi amfani da stream=true don kiraye-kirayen cloud kai tsaye. Runtime na gida ya haɗa da fallback na SSE→JSON.

Cloud Ya Ce An Haɗa Amma "API key Ba Ya Aiki"

Ƙirƙiri sabon key daga dashboard na gida (/api/keys)
Gudanar da aiki tare na cloud: Kunna Cloud → Sync Now
Tsofaffin keys/waɗanda ba a yi musu aiki tare ba na iya ci gaba da mayar da 401 a cloud

Matsalolin Docker

Docker IPv6 / Sake Saita Haɗi

Alamu: curl http://localhost:20128/v1/models yana mayar da curl: (56) Recv failure: Connection reset by peer. Dashboard da endpoints marasa tantancewa suna aiki, amma endpoints masu tantancewa suna gaza — yana kama da matsalar tantancewa amma ba haka ba ne.

Dalili: docker run -p 20128:20128 yana wallafawa a kan 0.0.0.0 (IPv4) da :: (IPv6), amma process ɗin da ke cikin container yana sauraro a kan IPv4 kawai. A hosts inda localhost ke fara resolve zuwa ::1, haɗin yana sauka a kan published port na IPv6 ba tare da listener a bayansa ba → ana sake saita haɗin.

Gyara:

Bincike mai sauri: Gudanar da curl -4 http://localhost:20128/v1/models. Idan yana aiki da -4 amma yana gaza ba tare da shi ba, kana da rashin daidaiton bind na IPv6.
Gyara na dindindin: Yi bind zuwa IPv4 kai tsaye ta amfani da -p 127.0.0.1:20128:20128 a cikin umarnin docker run ɗinka:
```
docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
  -p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest
```
Wannan yana tilasta bind na IPv4 sannan kuma yana hana fallasa proxy a kan dukkan interfaces na host.

Kayan Aikin CLI Yana Nuna Ba a Shigar da Shi Ba

Duba filayen runtime: curl http://localhost:20128/api/cli-tools/runtime/codex | jq
Don portable mode: yi amfani da image target runner-cli (CLIs da aka haɗa)
Don host mount mode: saita CLI_EXTRA_PATHS sannan ka mount directory na bin na host a matsayin read-only
Idan installed=true kuma runnable=false: an gano binary amma ya gaza healthcheck

Tabbatar da Runtime Cikin Sauri

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}'

Matsalolin Kuɗi

Kuɗaɗe Masu Yawa

Duba ƙididdigar amfani a Dashboard → Usage
Sauya primary model zuwa GLM/MiniMax
Yi amfani da free tier (Qoder, Kiro) don ayyukan da ba su da matuƙar muhimmanci
Saita iyakokin kuɗi ga kowane API key: Dashboard → API Keys → Budget

Gano da Gyara Matsaloli

Kunna Fayilolin Log

Saita APP_LOG_TO_FILE=true a cikin fayil ɗinka na .env. Ana rubuta logs na application a ƙarƙashin logs/. Ana adana artifacts na request a ƙarƙashin ${DATA_DIR}/call_logs/ lokacin da aka kunna pipeline na call log a cikin settings. Lokacin da aka kunna pipeline capture, saita CALL_LOG_PIPELINE_CAPTURE_STREAM_CHUNKS=false don cire payloads na stream chunk, ko daidaita CALL_LOG_PIPELINE_MAX_SIZE_KB don canza iyakar artifact a KB.

Duba Lafiyar Provider

# Dashboard na lafiya
http://localhost:20128/dashboard/health

# Binciken lafiyar API
curl http://localhost:20128/api/monitoring/health

Ma'ajiyar Runtime

Babban state: ${DATA_DIR}/storage.sqlite (providers, combos, aliases, keys, settings)
Amfani: Tables na SQLite a cikin storage.sqlite (usage_history, call_logs, proxy_logs) + ${DATA_DIR}/call_logs/ na zaɓi
Logs na application: <repo>/logs/... (lokacin da APP_LOG_TO_FILE=true)
Artifacts na call log: ${DATA_DIR}/call_logs/YYYY-MM-DD/... lokacin da aka kunna pipeline na call log

Aikin Clean history na shafin Request Logs yana share call_logs, tsohon request_detail_logs, da directory na artifact na gida ${DATA_DIR}/call_logs/.

Matsalolin Mai Katse Da'ira

Mai bayarwa ya maƙale a matsayin OPEN

Lokacin da mai katse da'irar wani mai bayarwa yake matsayin OPEN, ana hana buƙatu har sai lokacin jira ya ƙare.

Gyara:

Je zuwa Dashboard → Settings → Resilience
Duba katin mai katse da'ira na mai bayarwar da matsalar ta shafa
Danna Reset All don share duk masu katse da'ira, ko jira har lokacin jira ya ƙare
Tabbatar cewa mai bayarwar yana samuwa da gaske kafin sake saitawa

Mai bayarwa yana ci gaba da kunna mai katse da'ira

Idan mai bayarwa yana shiga matsayin OPEN akai-akai:

Duba Dashboard → Health → Provider Health don gano tsarin gazawar
Je zuwa Settings → Resilience → Provider Profiles sannan ka ƙara iyakar yawan gazawa
Duba ko mai bayarwar ya sauya iyakokin API ko yana buƙatar sake tabbatar da izini
Bincika bayanan ma'aunin jinkiri — jinkiri mai yawa na iya haifar da gazawar da ta danganci ƙarewar lokaci

Matsalolin Sauya Sauti Zuwa Rubutu

Kuskuren "Unsupported model"

Yi amfani da id na samfurin da ɓangarensa na farko ya kasance mai bayarwar da kake da bayanan shaidarsa (openai/whisper-1, openrouter/deepgram/nova-3). Amfani da deepgram/nova-3 kai tsaye yana buƙatar maɓallin Deepgram na asali.
Tabbatar cewa an haɗa mai bayarwar a Dashboard → Providers

Rubutaccen sakamakon sauti ya dawo fanko ko ya gaza

Duba nau'ikan fayilolin sauti da ake tallafawa: mp3, wav, m4a, flac, ogg, webm
Tabbatar cewa girman fayil ɗin yana cikin iyakokin mai bayarwar (yawanci < 25MB)
Duba ingancin maɓallin API na mai bayarwar a katin mai bayarwar

Gyaran Matsalolin Mai Fassara

Yi amfani da Dashboard → Translator don gano matsalolin fassarar tsari:

Yanayi	Lokacin Amfani
Playground	Kwatanta tsarin shigarwa/fitarwa gefe da gefe — liƙa buƙatar da ta gaza don ganin yadda ake fassara ta
Chat Tester	Aika saƙonni kai tsaye kuma bincika cikakken bayanan buƙata/amsa, har da headers
Test Bench	Gudanar da gwaje-gwajen rukuni a kan haɗaɗɗun tsare-tsare don gano fassarorin da suka lalace
Live Monitor	Kalli zirga-zirgar buƙatu a ainihin lokaci don gano matsalolin fassara masu faruwa lokaci-lokaci

Matsalolin tsari da aka fi samu

Alamun thinking ba sa bayyana — Duba ko mai bayarwar da ake nufi yana tallafawa thinking da kuma saitin kasafin thinking
Kiran kayan aiki yana ɓacewa — Wasu fassarorin tsari na iya cire filayen da ba a tallafawa; tabbatar da hakan a yanayin Playground
Umarnin system ya ɓace — Claude da Gemini suna sarrafa umarnin system ta hanyoyi daban-daban; duba sakamakon fassarar
SDK yana dawo da ɗanyen string maimakon object — An warware wannan a v1.x; mai tsabtace amsa yana cire filayen da ba na ƙa'ida ba (x_groq, usage_breakdown, da sauransu) waɗanda ke haifar da gazawar tantancewar Pydantic ta OpenAI SDK. Idan har yanzu kana ganin wannan a v3.x+, da fatan za ka shigar da rahoton matsala.
GLM/ERNIE yana ƙin rawar system — An warware wannan a v1.x; mai daidaita rawa yana haɗa saƙonnin system ta atomatik cikin saƙonnin mai amfani ga samfuran da ba su dace ba. Idan har yanzu kana ganin wannan a v3.x+, da fatan za ka shigar da rahoton matsala.
Ba a gane rawar developer ba — An warware wannan a v1.x; ana sauya ta atomatik zuwa system ga masu bayarwa da ba OpenAI ba. Idan har yanzu kana ganin wannan a v3.x+, da fatan za ka shigar da rahoton matsala.
json_schema ba ya aiki da Gemini — An warware wannan a v1.x; yanzu ana sauya response_format zuwa responseMimeType + responseSchema na Gemini. Idan har yanzu kana ganin wannan a v3.x+, da fatan za ka shigar da rahoton matsala.

Saitunan Juriya

Iyakance ƙima ta atomatik ba ta kunnawa

Iyakance ƙima ta atomatik tana aiki ne kawai ga masu samarwa masu amfani da maɓallin API (ba OAuth/biyan kuɗi ba)
Tabbatar cewa an kunna iyakance ƙima ta atomatik a Settings → Resilience → Provider Profiles
Duba ko mai samarwar yana mayar da lambobin matsayi na 429 ko kanun Retry-After

Daidaita jinkirin exponential backoff

Bayanan martabar masu samarwa suna goyan bayan waɗannan saituna:

Base delay — Lokacin jira na farko bayan gazawar farko (tsoho: 1s)
Max delay — Matsakaicin iyakar lokacin jira (tsoho: 30s)
Multiplier — Adadin ƙara jinkiri bayan kowace gazawa a jere (tsoho: 2x)

Hana cunkoson buƙatu lokaci guda

Lokacin da buƙatu masu yawa na lokaci guda suka isa ga mai samarwa da aka iyakance ƙimarsa, OmniRoute yana amfani da mutex + iyakance ƙima ta atomatik don jera buƙatun ɗaya bayan ɗaya da hana gazawa mai yaɗuwa. Wannan yana faruwa ta atomatik ga masu samarwa masu amfani da maɓallin API.

Buƙatun chat suna gazawa da 503 / chat_admission_busy

Alamomi:

Ƙarshen hanyar cika chat yana mayar da martanin 503 da za a iya sake gwadawa, wanda lambar kuskurensa ita ce chat_admission_busy.
Martanin yana ɗauke da Retry-After. Tun daga #12135 ana samo ƙimar daga yawan amfani da aka lura da shi — mafi girma tsakanin taga ta OMNIROUTE_CHAT_ADMISSION_QUEUE_MS da buƙatar ta riga ta jira da kuma tsawon lokacin da manyan leases na yanzu suka kasance a riƙe — ana zagaye ta zuwa cikakkun daƙiƙu kuma ana iyakance ta zuwa 60. A kan gate marar aiki tana riƙe da mafi ƙarancin ƙimomin tarihi: daƙiƙu 2 a hanyar da ta dogara da bytes, daƙiƙa 1 a hanyar da ta dogara da tsari (wadda kuma ta haɗa da reason: "structure_limit").
Wannan na iya faruwa yayin da wani babban chat ko martanin streaming mai ɗaukar lokaci mai tsawo yake ci gaba da gudana.

Jikin martanin da ya dogara da bytes shi ne:

{
  "error": {
    "message": "Chat admission capacity is temporarily unavailable. Retry shortly.",
    "type": "server_error",
    "code": "chat_admission_busy"
  }
}

Martanin da ya dogara da tsari yana amfani da type da code iri ɗaya, tare da saƙon Local chat admission capacity is busy for this structurally heavy request; upstream provider routing was not attempted. Retry shortly. da reason: "structure_limit". A tsoffin ma'aunan iyaka, ana ɗaukar buƙata a matsayin mai nauyin tsari idan tana da aƙalla saƙonni 200, aƙalla tools 64, ko aƙalla kimantattun tokens 32,000, ko kuma idan kimanta tsari mai iyaka ta cinye iyakokinta na nodes 10,000 da aka ziyarta ko zurfin 12.

Dalili: Wannan rage kaya ne da aka yi da gangan a cikin OmniRoute, ba gazawar mai samarwa na upstream ba. Kowane process yana amfani da kariya ta cikin process don tanadin iyakantacciyar damar manyan buƙatu kafin riƙewa da sarrafa babban jikin buƙata. Babban lease yana kasancewa a riƙe tsawon rayuwar martanin SSE.

#503-fanout: kafin wannan gyaran, kariyar tana iyakance concurrency da tsayayyen ADADIN buƙatu (OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT, tsoho 1) ba tare da la'akari da ƙwaƙwalwar host ba, don haka fan-out na coding-agent (subagents/CLIs da yawa, jikuna da a kai a kai suke > 256 KB) yana faɗuwa zuwa ingantaccen concurrency na kusan 1 kuma yana haifar da 503 a ƙarƙashin kaya na yau da kullum. Yanzu kariyar tana daidaita kanta: ana sarrafa ta da kasafin BYTES na ingest da ake samo ta atomatik (OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES) wanda aka tsara daga ainihin iyakar ƙwaƙwalwar process, sannan kuma tana duba alamar matsin albarkatu kai tsaye — don haka tana rage kaya ne kawai lokacin da host yake fuskantar matsin ƙwaƙwalwa na gaske, ba don kawai buƙatu masu nauyi fiye da ɗaya sun iso lokaci guda ba. Har yanzu ana mutunta tsohuwar iyakar adadi (OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT), amma sai idan ka saita ta kai tsaye.

Lokacin da damar take cike, babban buƙata da farko tana jira har zuwa OMNIROUTE_CHAT_ADMISSION_QUEUE_MS (tsoho 2000, 0 yana kashe jiran) domin wani gurbi ya samu kafin a mayar da 503 da za a iya sake gwadawa. An tanadi wannan iyakantaccen jira ne domin clients irin na agent (OpenCode, Claude Code, Cursor) waɗanda ke fan-out na manyan ƙananan buƙatu lokaci guda su jera cunkoson ɗaya bayan ɗaya maimakon ƙone duk kasafin sake gwadawarsu a kan ƙin karɓa nan take sannan su mutu a tsakiyar aiki. Ana nuna yawan amfani da manyan leases na yanzu, kasafin bytes da aka ƙayyade, da tsananin matsin kai tsaye a GET /api/monitoring/health → chatAdmission (inflightBytes, maxInflightBytes, budgetSource, pressureSeverity, countCapEnabled) — duba waɗannan kafin ka taɓa kowace env var. Settings → Resilience → Request Queue → Concurrent Requests ba ya sarrafa wannan; wannan saitin yana sarrafa wata dabara ta daban ta jerin buƙatun mai samarwa.

Gyara:

Da farko sake gwadawa. Ya kamata clients su mutunta Retry-After kuma su yi amfani da backoff maimakon maimaita buƙatar nan take.
Duba /api/monitoring/health → chatAdmission kafin daidaita komai. countCapEnabled: false da wadataccen maxInflightBytes suna nufin kasafin da aka samo ta atomatik yana riga yana yin aikinsa; pressureSeverity na high/critical yana nufin host ɗin yana fama da ƙarancin ƙwaƙwalwa na gaske — ba za a iya gyara wannan da admission env var ba, yana buƙatar ƙarin RAM ko ƙaramin workload.
Sai kawai idan /api/monitoring/health ya nuna cewa kasafin da aka samo ta atomatik ya yi ƙanƙanta sosai ga host ɗinka (abu ne da ba kasafai yake faruwa ba — yana riga yana daidaitawa daga container zuwa bare-metal), ka sauya shi kai tsaye da OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES maimakon komawa ga tsohuwar iyakar adadin buƙatu.

Duba manunin environment-variable domin saitunan admission masu cikakken iko.

Zaɓin RAG / LLM taxonomy na gazawa (matsaloli 16)

Wasu masu amfani da OmniRoute suna sanya gateway ɗin a gaban tarin RAG ko na agent. A irin waɗannan saitunan, ana yawan ganin wani baƙon yanayi: OmniRoute yana bayyana yana aiki yadda ya kamata (providers suna aiki, routing profiles suna daidai, babu sanarwar rate limit), amma amsar ƙarshe har yanzu ba daidai ba ce.

A aikace, waɗannan matsalolin yawanci suna fitowa ne daga RAG pipeline da ke ƙasa, ba daga gateway ɗin kansa ba.

Idan kana son ƙamus na bai ɗaya don bayyana waɗannan gazawar, za ka iya amfani da WFGY ProblemMap, wata hanya ta rubutu ta waje mai lasisin MIT wadda ke bayyana nau'ikan gazawar RAG / LLM guda goma sha shida da ke maimaituwa. A taƙaice, ya ƙunshi:

karkacewar retrieval da lalacewar iyakokin context
indexes da vector stores marasa komai ko waɗanda suka tsufa
rashin daidaito tsakanin embedding da ma'ana
matsalolin haɗa prompt da context window
rushewar dabaru da amsoshi masu nuna ƙwarin gwiwa fiye da kima
gazawar dogayen chains da daidaitawar agents
karkacewar memory da roles tsakanin agents da yawa
matsalolin tsarin deployment da bootstrap

Manufar mai sauƙi ce:

Lokacin da kake binciken amsa mara kyau, adana:
- aikin mai amfani da request
- haɗin route ko provider a OmniRoute
- duk wani RAG context da aka yi amfani da shi a ƙasa (retrieved documents, tool calls, da sauransu)
Daidaita matsalar da lamba ɗaya ko biyu na WFGY ProblemMap (No.1 … No.16).
Adana lambar a dashboard, runbook, ko incident tracker naka kusa da logs na OmniRoute.
Yi amfani da shafin WFGY da ya dace don yanke shawarar ko kana buƙatar canza RAG stack, retriever, ko routing strategy naka.

Cikakken rubutu da takamaiman hanyoyin aiwatarwa suna nan (lasisin MIT, rubutu kawai):

WFGY ProblemMap README

Za ka iya yin watsi da wannan sashe idan ba ka gudanar da RAG ko agent pipelines a bayan OmniRoute.

Sanannun Matsalolin v3.8.0

Matsalolin da suka kebanta da sakin v3.8.0 da hanyoyin wucin gadi na magance su a halin yanzu. Idan aka samar da gyara a wani patch na gaba, za a sabunta ko cire bayanin.

Gazawar auth na Devin CLI

Alamomi:

"Ba a sami Devin CLI ba" ko "auth ya gaza" lokacin kiran tools masu amfani da Devin
Binciken lokacin gudanar da CLI yana nuna installed=false

Dalilai:

CLI_DEVIN_BIN yana nuna wani path da babu shi
Ba a girka Devin CLI a host ɗin ba

Gyara:

Girka Devin CLI don platform ɗinka
Saita CLI_DEVIN_BIN=/usr/local/bin/devin (ko ainihin path ɗin) a cikin .env
Sake kunna OmniRoute sannan ka sake gwadawa daga Dashboard → Kayan Aikin CLI

Model cooldown ya makale (sake saitawa da hannu)

Alamomi:

Wani model yana ci gaba da bayyana a jerin cooldown ko da bayan lokacin ƙarewa ya wuce
Requests har yanzu suna tsallake model ɗin a combo routing duk da cewa timestamp ɗin yana nuna lokacin da ya wuce

Sake saitawa da hannu:

Dashboard: Settings → Model Cooldowns → danna Re-enable a kan card ɗin da abin ya shafa
API: DELETE /api/resilience/model-cooldowns tare da management auth headers

Haɗin Command Code provider ya gaza da 403

Alamomi:

403 lokacin gwada haɗin Command Code provider
Card ɗin provider yana nuna "ba a ba da izini ba" bayan an ƙara shi sabo

Dalili: OAuth flow bai kammala ba (ba a karɓi callback ba ko ba a adana token ba).

Gyara:

Gudanar da omniroute providers daga CLI don sake kunna OAuth flow, ko
Sake gudanar da OAuth daga Dashboard → Providers → Command Code → Reconnect

ModelScope yana mayar da cooldowns na 429 masu tsauri

Alamomi:

Cooldowns masu gajarta sosai ko na nan take a ModelScope bayan ƙaramin tarin requests
Combo routing yana tsallake ModelScope da wuri fiye da yadda ake tsammani

Dalili: ModelScope yana fitar da Retry-After headers na musamman ga provider. v3.8.0 ya zo da keɓantaccen tsarin sarrafa waɗannan headers, saboda haka tsofaffin versions suna kuskuren karanta su a matsayin shawarwarin rate-limit na gama-gari.

Gyara:

Tabbatar kana amfani da v3.8.0 ko sabo
Tabbatar an kunna useUpstream429BreakerHints toggle a ƙarƙashin Settings → Resilience

Babu OMNIROUTE_WS_BRIDGE_SECRET a production

Alamomi:

401 a kowane Codex/Responses WebSocket bridge request lokacin gudanarwa a remote production host
WebSocket bridge handshake yana rufewa nan take bayan haɗawa

Dalili: Babu env var na OMNIROUTE_WS_BRIDGE_SECRET a production environment.

Gyara:

Ƙirƙiri random secret: openssl rand -hex 32
Saita OMNIROUTE_WS_BRIDGE_SECRET=<random-secret> a cikin env na production server (da duk wani client da ke sadarwa da bridge)
Sake kunna OmniRoute

Responses API: background mode ya koma synchronous

Alamomi:

An rubuta gargadi a log: background mode degraded to synchronous
Request mai background: true yana mayar da amsar synchronous ta al'ada maimakon background job handle

Dalili: v3.8.0 da gangan yana sauya background: true a Responses API zuwa synchronous execution tare da fitar da gargadi. Cikakken async background execution wani abu ne da za a samar nan gaba.

Gyara:

Daidaita client ɗin ya yi kira ba tare da background ba, ko
Jira wani sakin na gaba wanda zai zo da cikakken async background mode (bi diddigin changelog)

Jinkirin Farawa / Ƙarewar Lokacin Jira

Idan CLI ya nuna ⚠ Server did not respond within 60s amma a zahiri uwar garken tana aiki, lokacin da aka ware wa binciken shiri ya yi gajarta ga muhallinka.

Wannan yawanci yana faruwa ne a Windows (riga-kafi, masu sa ido kan tsarin fayiloli) ko cikin containers masu nauyin ayyuka yayin farawa.

Gyara — ƙara lokacin da aka ware:

# Ta hanyar env var (yana dorewa a duk lokacin farawa):
export OMNIROUTE_READY_TIMEOUT_MS=180000   # mintuna 3
omniroute serve

# Ta hanyar alamar CLI (sau ɗaya kawai):
omniroute serve --ready-timeout 180000

Tsohon ƙima ita ce 60 000 ms (60 s). Gargadin na bayar da bayani ne kawai; uwar garken za ta ci gaba da farawa a bango kuma za a iya isa gare ta da zarar farawa ya kammala.

Duba docs/reference/ENVIRONMENT.md don cikakkun bayanai game da OMNIROUTE_READY_TIMEOUT_MS.

Har Yanzu An Maƙale?

Matsalolin GitHub: github.com/diegosouzapw/OmniRoute/issues
Tsarin Gina Manhaja: Duba docs/architecture/ARCHITECTURE.md don bayanan ciki
Manazartar API: Duba docs/reference/API_REFERENCE.md don duk endpoints
Dashboard na Lafiyar Tsari: Duba Dashboard → Health don ganin matsayin tsarin kai-tsaye
Mai Fassara: Yi amfani da Dashboard → Translator don gano matsalolin tsari

FilesExpand file tree

TROUBLESHOOTING.md

Latest commit

History

TROUBLESHOOTING.md

File metadata and controls

Troubleshooting (Hausa)

Bayani Cikin Sauri

Cikakken Jagorar Warware Matsala

Taƙaita Yawan Buƙatu a Masu Bayarwa na Kyauta (429 / 400 / 401)

Gargaɗin npm install (ERESOLVE / peer / deprecated)

Gemini Web da Playwright Chromium

Gyare-gyare Masu Sauri

Gargaɗin Ƙarya na Antivirus

Avast/AVG yana keɓe README.md da MD:HttpRequest-inf[Susp]

Kaspersky yana yi wa manhajar Desktop alama da PDM:Trojan.Win32.Generic

Daidaituwar Node.js

Shafin shiga yana rushewa ko yana nuna kuskuren "Module self-registration"

npm v11+: Ba a shigar da better-sqlite3 ba (Cannot find module)

macOS: dlopen / "slice is not valid mach-o file"

Matsalolin Proxy

Tabbatar da mai bayarwa yana nuna "fetch failed"

Binciken lafiyar token yana gazawa da "fetch failed"

Proxy na SOCKS5 yana mayar da "invalid onRequestStart method"

Proxy na MITM a ƙarƙashin WSL: ba a katse manhajojin tebur a kan Windows host

Matsalolin Masu Bayarwa

"Language model did not provide messages"

Iyakance Adadin Buƙatu

Token na OAuth Ya Ƙare

Asusun Kiro da yawa: asusu na biyu yana mayar da na farko mara inganci

Matsalolin Cloud

Kurakuran Aiki Tare na Cloud

stream=false na Cloud Yana Mayar da 500

Cloud Ya Ce An Haɗa Amma "API key Ba Ya Aiki"

Matsalolin Docker

Docker IPv6 / Sake Saita Haɗi

Kayan Aikin CLI Yana Nuna Ba a Shigar da Shi Ba

Tabbatar da Runtime Cikin Sauri

Matsalolin Kuɗi

Kuɗaɗe Masu Yawa

Gano da Gyara Matsaloli

Kunna Fayilolin Log

Duba Lafiyar Provider

Ma'ajiyar Runtime

Matsalolin Mai Katse Da'ira

Mai bayarwa ya maƙale a matsayin OPEN

Mai bayarwa yana ci gaba da kunna mai katse da'ira

Matsalolin Sauya Sauti Zuwa Rubutu

Kuskuren "Unsupported model"

Rubutaccen sakamakon sauti ya dawo fanko ko ya gaza

Gyaran Matsalolin Mai Fassara

Matsalolin tsari da aka fi samu

Saitunan Juriya

Iyakance ƙima ta atomatik ba ta kunnawa

Daidaita jinkirin exponential backoff

Hana cunkoson buƙatu lokaci guda

Buƙatun chat suna gazawa da 503 / chat_admission_busy

Zaɓin RAG / LLM taxonomy na gazawa (matsaloli 16)

Sanannun Matsalolin v3.8.0

Gazawar auth na Devin CLI

Model cooldown ya makale (sake saitawa da hannu)

Haɗin Command Code provider ya gaza da 403

ModelScope yana mayar da cooldowns na 429 masu tsauri

Babu OMNIROUTE_WS_BRIDGE_SECRET a production

Responses API: background mode ya koma synchronous

Jinkirin Farawa / Ƙarewar Lokacin Jira

Har Yanzu An Maƙale?

Avast/AVG yana keɓe `README.md` da `MD:HttpRequest-inf[Susp]`

Kaspersky yana yi wa manhajar Desktop alama da `PDM:Trojan.Win32.Generic`

npm v11+: Ba a shigar da `better-sqlite3` ba (Cannot find module)

macOS: `dlopen` / "slice is not valid mach-o file"

`stream=false` na Cloud Yana Mayar da 500