JuliusBrussee/caveman · error · Error

cave_provider_terminal_${finalMessage.stopReason}

Error message

cave_provider_terminal_${finalMessage.stopReason}

What it means

Terminal-state guard: the provider run finished with stopReason 'error' or 'aborted', which is surfaced as a typed failure (cave_provider_terminal_error / cave_provider_terminal_aborted) rather than a silent empty answer.

Source

Thrown at packages/agent/src/runtime.ts:2111

        (efficiencyPlan !== undefined ||
          executionContext.spendLedgers.length > 0 ||
          usageFailure.message === "cave_provider_model_identity_mismatch" ||
          usageFailure.message === "cave_provider_identity_missing")) {
      throw usageFailure;
    }
    if (pendingSpendReservations.length > 0) {
      markSpendIncomplete(executionContext.spendLedgers);
      throw new Error("cave_subagent_spend_evidence_incomplete");
    }
    // A run stopped before its first call has no assistant message, and that is
    // the honest outcome rather than missing evidence: the caller gets an empty
    // answer, zero usage, and the reason the runtime declined to spend.
    if (!finalMessage && stopReason === undefined) {
      throw new Error("cave_incomplete_evidence: Pi emitted no final assistant message");
    }
    if (finalMessage &&
        (finalMessage.stopReason === "error" || finalMessage.stopReason === "aborted")) {
      throw new Error(`cave_provider_terminal_${finalMessage.stopReason}`);
    }
    const text = finalMessage === undefined ? "" : assistantText(finalMessage);
    if (definition.output?.schema && finalMessage !== undefined) {
      let parsed: unknown;
      try {
        parsed = JSON.parse(text);
      } catch {
        throw new Error("cave_output_schema_invalid_json");
      }
      if (!Value.Check(definition.output.schema, parsed)) {
        throw new Error("cave_output_schema_mismatch");
      }
    }
    if (appliedPlan.appliedTransformIDs.length > 0 && !cacheBoundaryKnown) {
      cacheBust = true;
      markRequestPassThrough(headers, appliedPlan, "cache_boundary_unobserved");
    }
    for (const child of nestedReceipts) receipt.recordSubagent(child);

View on GitHub (pinned to 766dce6b13)

Solutions

1. Parse the stop reason after the cave_provider_terminal_ prefix to get the provider cause
2. Retry on transient provider errors; inspect provider diagnostics otherwise
3. Check abort signals — an aborted request surfaces here

When it happens

Trigger: Thrown at packages/agent/src/runtime.ts:2111 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of JuliusBrussee/caveman@766dce6b13 (2026-08-18). Data as JSON: /api/errors/35e6bfa412b99937. Report an issue: GitHub.