> For the complete documentation index, see [llms.txt](https://docs.finchagentic.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.finchagentic.com/troubleshooting.md).

# Troubleshooting

## Tools not appearing

1. Restart the MCP client fully (not just reload window)
2. Confirm config path for your client ([install.md](/install.md))
3. `npx clear-npx-cache` then restart
4. Run `finch doctor`

## Old version stuck

```bash
npx clear-npx-cache
npx -y -p @finchagentic/mcp@4.0.0 finch --version
```

Ensure every client entry pins `@4.0.0`.

## Auth / session errors

* Cloud vault/agents need `FINCH_SESSION_TOKEN`
* Local vault mode works without account for core vault tools
* Re-login from Finch App if token expired

## `web_search` / scrape weak or failing

Set `FIRECRAWL_API_KEY` in MCP env. Without it, quality falls back or fails depending on path.

## Swap refused

* Price impact over cap
* Missing estimate/preview/confirm
* Wrong family: Base → `base_mcp_*`, Robinhood Chain stocks → `rh_mcp_*` (not 0x Base tools)

## GitHub tools

Need `GITHUB_TOKEN` for search/private ops.

## Rate limits (429)

Many paths auto-retry with backoff. Wait; don’t hammer.

## Diagnose anything

```bash
finch doctor
```

## App Terminal has no tools

* Convex `noelShell` must be deployed (`npx convex dev`)
* Frontend falls back to plain chat if shell action fails
* Terminal tool set ≠ full MCP 121 tools

## API Market buyer errors

* Invalid / revoked API key
* Budget hard-cap hit (402-style)
* No healthy offers for model
* Settlement disabled at soft-launch (off in **all** environments, including prod)

## Still stuck

1. `doctor` output
2. MCP client logs
3. Package version
4. Whether local vault is on
5. Exact tool name that failed


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.finchagentic.com/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.