> ## Documentation Index > Fetch the complete documentation index at: https://docs.fetchhive.com/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Fix common Hive Agent setup, source, budget, cancellation, trace, and cost issues Use this page when a Hive Agent does not start, pauses unexpectedly, fails during source preparation, or produces confusing logs. ## The run says a Default API key is required Dashboard-started Hive Agent runs require an active workspace **Default** API key. Open [API Keys](../workspace/api-keys), create or reactivate a key, and mark it as the default key for the workspace. Then start the run again. ## Source preparation failed Source preparation runs before planning. If a website or file source cannot be processed, the run fails before the planner starts. Check that: * Website URLs are reachable * Uploaded files are supported: PDF, DOC, DOCX, TXT, MD, CSV, XLS, or XLSX * Knowledge Bases are active * Knowledge Base items still exist * File uploads belong to the same workspace Open the run detail sheet and inspect the source list for the source-specific error. ## The run is blocked A blocked run usually needs budget approval or has reached a budget gate. Check **Budget Settings** on the Hive Agent. If the run crossed the **Budget Hint (USD)** with **Conservative** strictness, approve the magic link or decline it. If the run reached the **Budget Cap (USD)**, approve enough additional budget to leave room for execution, verification, and final composition. A run can block during Compose even after all nodes verified. If the editor control bar shows **Budget stop**, that previous run already ended on budget (`budget_block_state: stopped`). Raise the cap or start a new run with **Start Run** — the stopped run no longer occupies the live-run control. ## The run failed after max passes The run can stop when it reaches **Max repeat passes** or when final composition fails verification after **Max compose attempts**. If nodes are verified but Compose failed, open the final response section and read the compose issue. The verified node outputs are still available as supporting detail, but the final composed response did not pass the assembly check. On the Compose card in the run console, click **Retry compose** to re-run only the compose stage. You can raise the budget cap with an optional additional budget amount before confirming. Compose retry keeps verified node outputs and does not re-run plan, execute, or verify. Open the run detail sheet and read the verifier rejection reasons. Then tune the stage that caused the failure: * Improve sources or **PLAN** if nodes are unclear * Add tools or change **EXECUTE** if the agent cannot produce the required output * Adjust **VERIFY** if the verifier is too strict or too loose * Adjust **COMPOSE** if verified node outputs are correct but the final response omits, distorts, or formats them poorly * Use **Best effort** if partial verified node output is acceptable — after max passes it will still try Compose from verified nodes when at least one node verified * If verifier rejections keep citing mismatched Source `[N]` numbers across multi-file sources, raise Knowledge Base item chunk length, switch to Advanced chunking, re-embed, and prefer a stronger EXECUTE model (see [Testing and Iteration](./testing-and-iteration#large-source-objectives)) * A completed best-effort run can still show a Max passes message in the detail view while `status` is `completed` — check status and whether a final response / composition was stored, not only the error text ## Nodes keep failing with missing evidence / UNVERIFIED placeholders If execute outputs admit they never opened the brief/spreadsheet, or alternating passes bounce between `check_failed:required_nonblank` and `unsupported_source_claim` / `missing_required_evidence`, the executor likely received **no SOURCE CONTEXT**. Check in order: 1. Knowledge Base **search score threshold** — platform default is about **0.1** for hybrid search. A threshold of **0.5** is retrieval-hostile for long multi-document agent queries and can return zero chunks even when embeddings exist. 2. Knowledge Base **search chunk limit** — platform default is **8**; raise toward 10–20 for multi-file sources. 3. Item chunking — Advanced + \~1500 max length, then re-embed and confirm item `run_status` is completed. 4. On the execute attempt payload, inspect `source_chunks` and `source_retrieval`: * Empty `source_chunks` with ready sources means retrieval failed after the platform degrade ladder. * `source_retrieval.stages` shows clamped-threshold → floor-threshold → raw-document-fallback attempts, plus per-request HTTP success/errors. Plan / execute / verify / compose do not receive system `file_tools`; grounding is `SOURCE CONTEXT` only. Downloadable Hive Agent files are produced by the platform after compose and appear on the run alongside the text final response. After a platform deploy, retrieval that exhausts the degrade ladder with zero chunks (`empty_reason: all_stages_empty`) fails the run immediately with `source_retrieval_empty` instead of burning the full pass budget. Missing API keys / blank queries (`no_requests`) still soft-degrade and continue without SOURCE CONTEXT. ## The run failed with provider\_account\_error Provider billing/quota errors (for example Anthropic `credit balance is too low`) stop the Hive Agent run instead of consuming remaining execute/verify passes. Top up the provider account / workspace BYOK integration, then start a new run. ## The run was cancelled Hard-stop cancellation stops the run quickly and marks remaining node work cancelled. Partial-result cancellation stops new work, lets already-started work finish, and keeps verified node output in the run detail sheet. If cancellation happens during Compose, the in-flight compose attempt may finish, but no further compose attempts are scheduled. The terminal status is still `cancelled`. If a run still looks live in logs after the platform has already stopped it, **Cancel run** still marks the Fetch Hive run cancelled. You do not need an active backend execution for cleanup. You can also cancel stuck runs for archived Hive Agents from Hive Agent logs. Archived blueprints cannot start new runs. ## Trace details look delayed or incomplete Child AgentRun traces can arrive after their parent Hive Agent stage. Refresh the detail sheet after the child run finishes. Use the request ID from the log row or stage detail to open the run directly from global search. If a budget gate or step-cost bar looks far longer than its parent Execute / Verify row, refresh after the run finishes. Budget markers are zero-duration points on the stage timeline; a background sync after the stage completes moves them onto the correct anchor. ## The run cost is higher than expected Check: * **Max Concurrent Nodes** * **Max repeat passes** * **Max compose attempts** * Source preparation costs * Number of planned nodes * Executor and verifier models * Tool calls made by executor nodes * Whether rejected nodes repeated through multiple passes * Whether the final response needed multiple compose attempts Lower concurrency, use a tighter objective, attach fewer sources, set a lower **Budget Cap (USD)**, or use **Conservative** strictness when you want the run to pause earlier. See also: [Budget Approval](./budget-approval) and [Logs](./logs).