Skip to content

Troubleshooting

← Home

Docker daemon is unavailable

error: Docker daemon is unavailable: …

Start Docker Desktop (macOS/Windows) or the Docker daemon (Linux) and retry. Verify with docker info. nfind checks Docker before generating any code, so this fails fast and costs no API call.

Docker CLI was not found

error: Docker CLI was not found. Install Docker and ensure 'docker' is on PATH.

Install Docker (see Installation) and make sure the docker command is on your PATH.

OpenAI authentication errors

If generation fails with an authentication or "missing API key" error, set your key:

export OPENAI_API_KEY=sk-...

The host needs network access to reach the API. (The worker container does not — and shouldn't have network access; that's by design.)

Model was not found

error: Model 'gpt-5.0' was not found for the 'openai' provider -- it may be
misspelled or not enabled for your API key. Run 'nfind --list-models' to see
what's available.

The model id in --model is unknown to the provider or not enabled for your key. List the valid ids and copy one:

nfind --list-models                    # for the default (OpenAI) provider
nfind --list-models --model groq/x     # for another provider

Note this is not the error for OpenAI reasoning/codex models that are served only on the /responses endpoint (e.g. gpt-5.1-codex-mini) — nfind detects those and switches endpoints automatically, so they work without any flag. See endpoint selection.

No results when there should be some

  • Wrong directory. nfind searches the PATH argument, defaulting to the current directory. Pass the directory explicitly: nfind "…" ~/Music.
  • Empty output is valid. Exit code 0 with no lines means the filter matched nothing. Inspect what it actually did with --show-code:
nfind "audio files" ~/Music --show-code
  • Prompt too narrow or ambiguous. Rephrase more explicitly, e.g. list the extensions you mean: "audio files with extension mp3, flac, or wav".

The filter timed out

error: Generated filter exceeded the 10s timeout.

Content-heavy prompts over large trees can exceed the default limit. Raise it:

nfind "text files containing a TODO comment" . --timeout 60

If it still times out, narrow the search path or make the prompt more selective.

Results look wrong or inconsistent

The filter is generated by a model, so phrasing matters and runs can vary. To diagnose and stabilise:

  • Use --show-code to see exactly what ran.
  • Use --confirm to approve the code first.
  • Be explicit in the prompt (extensions, thresholds, "directly inside" vs. "anywhere beneath"). See Examples for well-formed prompts.
  • A stronger model can help: nfind "…" --model gpt-4o.

Worker image build is slow or fails

The first run builds nfind-search-paths:latest and must pull python:3.11-slim once, which needs network access. If a build hangs, raise --build-timeout, or rebuild explicitly:

nfind "files with no extension" . --rebuild --build-timeout 300

Searches are slow on large trees

nfind enumerates every path under the search root before generating code, and the filter then runs over that whole list inside the container. For very large trees, search a more specific subdirectory, or raise --memory / --cpus if the worker is resource-bound:

nfind "…" ./subdir --memory 512m --cpus 2

Worker runs out of memory on very large trees

The paths are serialized to JSON and piped into the container, then deserialized back into a Python list — so the worker holds both the JSON bytes and the list in memory at once. At the default 256 MB limit this can OOM around 500K–1M paths (depending on average path length). Raise the limit:

nfind "…" . --memory 1g

If the search root is large, also consider narrowing it or using --exclude to prune subtrees you don't need before the paths reach the container.