Skip to main content
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, 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)
  • 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 and Logs.