Troubleshooting
This page summarizes common nb-search error codes, their causes, and the corresponding fixes.
CLI exit-code quick reference
| Exit code | Meaning | Description |
|---|---|---|
0 | Success | The operation succeeded, including an offline doctor check, capability output, or an acknowledged cancellation request |
2 | Error | Invalid call parameters, configuration errors, network-transfer errors, protocol-validation failures, job failures, or a migration block |
3 | Partial success | The logical result is partial, or the migration report is partially complete |
4 | Empty result | Search or fetch completed successfully but matched no results |
5 | Wait timeout | The --wait budget was exhausted, or the underlying task reached its timeout threshold |
6 | Cancelled | The job was explicitly cancelled by the caller |
7 | Job in progress | The asynchronous job is still in queued or running state |
Diagnose core error codes
DEFAULT_NOT_CONFIGURED
- Cause: In version
0.5.0and later,defaults.search_lane = "duckduckgo.search"is configured by default. This error occurs only when the configuration file or a host override explicitly clearsdefaults.search_lane(sets it tonull) and the search call does not pass--lane,--lanes, or--preset. - Fix: Pass an explicit
--lane <lane_id>on the command line, or restore"defaults": { "search_lane": "duckduckgo.search" }(or another configured source such as"tavily.search") inconfig.json.
CREDENTIAL_NOT_CONFIGURED / LANE_NOT_CONFIGURED
- Cause: The environment-variable key required by the target Lane is missing or an empty string, or the Provider instance is disabled.
- Fix: Run
node scripts/nb-search.mjs capabilitiesto inspect what is missing for the Lane, then set the correspondingNB_SEARCH_*_API_KEYin the environment or in a protected credential file.
ENDPOINT_NOT_CONFIGURED
- Cause: A source that requires a custom base endpoint (such as
searxng.search,gma.research, oroac.synthesis) was used without configuring its BASE_URL environment variable. - Fix: Check that variables such as
NB_SEARCH_SEARXNG_BASE_URLorNB_SEARCH_GROK_MULTI_AGENT_BASE_URLare set.
LANE_EXECUTION_UNSUPPORTED
- Cause: The requested execution mode is not supported by the source. For example, a synchronous request was sent to the asynchronous-only
browser.render, or an asynchronous request was sent to a custom query that supports only synchronous execution. - Fix: Use the static capability catalog to select a supported
syncorasyncexecutionmode.
FETCH_CHAIN_UNAVAILABLE
- Cause: No Pipeline was specified, and the built-in default fetch chain cannot satisfy the current input source, or none of the Pipelines in the chain is ready.
- Fix: Specify the concrete Pipeline explicitly with
--pipeline, or complete thefetch_chainconfiguration for the relevant input type.
FETCH_BLOCKED
- Cause: The target URL violates the SSRF security policy, including a private IP, loopback address, cloud metadata address, or a redirect to a private-network address.
- Fix: Ensure that the target is a publicly resolvable public HTTP(S) address. SSRF protection is a hard policy and cannot be bypassed.
FETCH_BYTES_LIMIT
- Cause: A fetch input source (local text or file) exceeds
execution.fetch.max_source_bytes, or an HTTP response body exceedsmax_response_bytes. - Handling: Distinguish the input and response paths. An oversized local input is rejected before entering the Pipeline; an oversized third-party proxy-fetch API response fails as a transport error; the
direct.fetchPipeline may truncate an oversized response within bounds and return it. See Content Fetching: Security Limits for the exact mechanism. Optimize the target content or adjust configuration for the actual scenario; do not blindly increase the limit.
FETCH_CONTENT_TYPE_REJECTED
- Cause: The response MIME type is not in the allowlist.
- Fix: Confirm that the target content type is
text/html,text/plain, ortext/markdown.
QUALITY_GATE_FAILED
- Cause: The fetched body has fewer characters than the explicitly configured lower gate (
min_content_chars), or it contains a blocking marker. - Fix: Check whether the target site requires JavaScript rendering. If so, use
browser.renderasynchronously, or adjustquality.min_content_charsin the configuration.
OUTPUT_TOO_LARGE
- Cause: In synchronous mode, the response envelope exceeds
execution.max_inline_bytes(16 MiB by default). - Handling: The system does not automatically truncate a synchronous envelope. In fetch pipelines,
direct.fetchanddirect.localsupport bothsyncand detachedasync;browser.rendersupports onlyasync; the other six third-party cloud pipelines (jina.reader,exa.contents,tavily.extract,firecrawl.scrape,wayback.fetch, andoac.fetch) support onlysync. When the limit is exceeded, fetch can reducemax_content_chars(or explicitly use--execution asyncon a pipeline that supports asynchronous execution), while search can reducemax_resultsor switch to--execution async. Rerunning a paid-source request may incur additional charges; check the budget first.
ENTRY_UNAVAILABLE
- Cause: The build artifact
dist/cli.mjscannot be found when starting throughscripts/nb-search.mjs. - Fix: When running from source, first run
pnpm buildfrom the repository root. When bringing it in as a Skill dependency, make sure the entiredist/directory is present.
Offline configuration validation and capability inspection
When diagnosing configuration or credential-binding problems, start with the offline diagnostic command:
node scripts/nb-search.mjs --doctorThis command validates only local configuration syntax and the presence of credential environment variables. It reports syntax and slot summaries, but it does not prove that runtime ports are ready and does not make an external network request to verify that credentials are actually usable.
To view source readiness and supported execution modes:
node scripts/nb-search.mjs capabilitiesIn the returned catalog, inspect each source's availability (ready or unavailable), issues list, and supported execution_modes. Even ready means only that local initialization completed; it does not indicate the upstream service's current network connectivity or quota health.