| summary | Troubleshooting: every error modsearch can print, what causes it, what to do | |||
|---|---|---|---|---|
| read_when |
|
English | 简体中文
Every message below is one modsearch actually prints. Search this file for the words you saw.
Before decoding a message, run modsearch doctor. It reports your Node version, every engine's readiness per role and why (binary on PATH, key from env or file, Grok login file present), where your config comes from, its file permissions, and the private-network state, all without spending quota or making a request. Missing pieces come with a copyable fix command. Most setup problems are visible there at a glance. Add --json to feed the report to a tool.
No engine on this machine can search the web. Any one of these enables it:
- antigravity-cli: install Antigravity CLI and sign in once (free, no key)
- tavily: set a Tavily key (free tier: 1,000 credits/month, no card)
- exa: set an Exa key ($10/month recurring free credit, ~1,400 searches, no card)
- firecrawl: set a Firecrawl key (1,000 free credits/month, no card)
No search engine is set up. Every fix is listed because each is real: agy needs no key but has a weekly quota, the others need a key but each carry their own free budget.
curl -fsSL https://antigravity.google/cli/install.sh | bash && agy # then sign in
# or any keyed engine:
modsearch config set tavily.apiKey <key>
modsearch config set exa.apiKey <key>
modsearch config set firecrawl.apiKey <key>Page fetch (-u) is unaffected by this: it always works.
Individual quota reached. Please upgrade your subscription ... Resets in 94h19m9s.
agy's free tier is one weekly grant shared by the Antigravity desktop app, the CLI, and the SDK, and parallel subagents drain it faster. Three ways out:
- Wait for the reset named in the message.
- Add a keyed search engine (Tavily, Exa, or Firecrawl). Search then falls through to it automatically, with no further action from you.
- With cooldown on (the default), agy is remembered as spent and moved to the back of the chain until it resets, so later runs fail over first. See "An engine keeps getting skipped" below.
exa rejected the API key (401). Fix it: modsearch config set exa.apiKey <key>
firecrawl rejected the API key (401). Fix it: modsearch config set firecrawl.apiKey <key>
The key is missing, wrong, or revoked. Set a valid one with the command in the message, or export EXA_API_KEY / FIRECRAWL_API_KEY. A rejected key is a setup problem, not a quota problem, so it is not put on cooldown.
exa is out of credits: ...
firecrawl is out of credits: ...
The engine's free budget for the period is spent. Another keyed search engine picks up the work on its own, and with cooldown on the spent engine is moved to the back of the chain until it recovers, so you stop hitting it. Add credit, switch engines, or wait for the monthly reset.
tavily is out of monthly quota (HTTP 432). ...
Tavily returns 432 (plan usage cap) and 433 (PAYGO cap) when the monthly budget is spent. modsearch reads these as the monthly quota class, so with cooldown on the engine is held for a full day rather than the 45-minute default, since retrying inside the hour just re-hits the same wall. Another search engine picks up the work meanwhile. Add credit at https://app.tavily.com or wait for the monthly reset.
modsearch is failing over around a cooldown. When an engine hit a quota wall, it is remembered in ~/.modsearch/state.json and tried last until it recovers, and the result's warnings name which engine and until when. Run modsearch doctor to see what is cooling and how much time is left. To clear it by hand:
modsearch state clearTo turn the behavior off entirely, so routing is exactly as it was before: modsearch config set cooldown off. A cooling engine is never removed, only reordered, so it is still tried when everything else fails.
Read results[].engine in the output. Engines are chosen per run from what is installed, so this is usually correct rather than broken:
- Expected agy, got
tavily: agy failed or is unavailable, and Tavily picked up the work. Thewarningslist names the fallback andattemptscarries agy's exact failure. - Expected agy, got
localon a fetch: same story, and the page came back as served with no summary or focus narrowing (warningssays so). - Asked about X, got
antigravity-cliortavily: Grok Build is missing or signed out, so this is second-hand web evidence. Thewarningslist says so explicitly.
Force one engine with -e <name> when you need to be sure.
Blocked private network target: example.com -> 198.18.91.58. If a VPN or proxy on
this machine maps public hosts into reserved ranges, allow it with
--allow-private-network, or: modsearch config set allowPrivateNetwork true
The SSRF guard refused an address in a reserved range. Two very different causes:
- A VPN or proxy mapping public hostnames into ranges like
198.18.0.0/15. Common with split-tunnel clients. Allow it with the flag or the config setting above. - A genuinely internal address, which is exactly what the guard exists for. Do not disable the guard to reach it.
The local engine runs no JavaScript. A page rendered entirely client-side has almost nothing in its HTML, and the result says so in uncertainty. Options: fetch it through agy instead (-e antigravity-cli), or find a server-rendered URL for the same content.
-e/--engine is a hard force: it uses exactly that engine, with no fallback. When the forced engine is a typo, cannot do the job, or fails at runtime, the run errors rather than quietly switching to another engine and spending its quota.
Unknown engine "tavil" (--engine). Drop -e to let modsearch pick one that works, or name a known engine: ...
A typo. Fix the spelling, or drop -e to let modsearch choose automatically.
The tavily engine cannot fetch (--engine forces it with no fallback). Drop -e to let modsearch pick an engine that can. ...
You forced a search-only engine to read a page. Drop -e and let modsearch route, or force -e antigravity-cli (which can fetch).
Cannot read /Users/you/.modsearch/config.json: EACCES ... Fix the file or its permissions.
The file exists but cannot be read. A missing file is fine (that is the zero-config path), so this is a real permissions or file-type problem worth fixing rather than something to ignore. On Windows the file lives at %USERPROFILE%\.modsearch\config.json.
Failed to parse ... Fix or delete the file.
Invalid JSON. modsearch config init --force rewrites a clean one, losing whatever was in it.
antigravity-cli engine timed out after 210000 ms.
Retry once with --timeout 300000. If it still times out, the engine is stuck rather than slow: check agy interactively. Engines that ignore SIGTERM are escalated to SIGKILL, so a timeout always returns promptly even when the process does not cooperate.
Every engine for the web source failed.
- antigravity-cli: ...
- tavily: ...
Each engine's own failure is listed in order. Act on the first fixable one, usually a quota or a key.
Re-run with the failing command exactly as modsearch printed it, and include that output in an issue: https://github.com/liustack/modsearch/issues