> ## Documentation Index
> Fetch the complete documentation index at: https://kestrel.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose empty results, missing content, provider failures, and agent discovery.

# Troubleshooting

## The command is not found

Confirm that the installation directory is on your `PATH`:

```bash theme={null}
kestrelsearch --help
```

With uv, inspect installed tools:

```bash theme={null}
uv tool list
```

## A search returns no results

Try another provider or an ordered fallback:

```bash theme={null}
kestrelsearch search "your query" \
  --engine duckduckgo \
  --engine bing \
  --engine yahoo \
  --mode fallback
```

Provider HTML and throttling can change. Narrow region or recency filters may
also reduce results.

## An all-`--query` command reports `Missing argument 'QUERY'`

Current versions accept one or more `-q` or `--query` options without a
positional query:

```bash theme={null}
kestrelsearch search \
  -q "first query" \
  -q "second query" \
  --output json
```

If this form reports `Missing argument 'QUERY'`, upgrade the installed tool:

```bash theme={null}
uv tool upgrade kestrelsearch
```

As a compatibility workaround for an older installation, make the first query
positional and use `-q` for the remaining queries.

## Results have null content

`content` is null when:

* `--no-fetch` is active.
* The URL points to a PDF.
* The response has an unsupported content type.
* The response exceeds `--max-response-bytes`.
* The page times out, rejects the request, or cannot be parsed.

Try a longer timeout or a larger response limit only when the added latency and
memory are acceptable:

```bash theme={null}
kestrelsearch search "your query" \
  --timeout 20 \
  --max-response-bytes 4000000
```

## The agent does not discover the skill

Install it for the intended agent and scope, then restart the agent session:

```bash theme={null}
kestrelsearch skill install --agent codex --scope project
```

See [agent integration](/guides/agent-integration) for installation paths.

## Inspect diagnostic events

Kestrel writes best-effort JSONL diagnostics under:

```text theme={null}
~/.kestrel/logs/YYYY-MM-DD/events.jsonl
```

Events may record retries, provider failures, partial fanout failures, skipped
responses, and fetch errors. Diagnostic logging never blocks a search result.