JuliusBrussee/caveman · error

cave_context_segment_missing:${id}

Error message

cave_context_segment_missing:${id}

What it means

Thrown by assembleSystemPrompt when a required context segment id ("agent.instructions" or one of definition.contexts[].id) has no matching segment in lowered.ir.segments. The lowering pipeline and the agent definition have diverged.

Source

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

    ["results_artifacts", (bill.artifact ?? 0) + (bill.skill ?? 0) + (bill.tool_result ?? 0)],
    ["output", outputMaxTokens],
  ];
  for (const [slot, used] of slots) {
    if (used > plan.budgets[slot]) throw new Error(`cave_${slot}_budget_exceeded`);
  }
}

export function assembleSystemPrompt(
  definition: AgentDefinition,
  lowered: LoweredContext,
  bodies: ReadonlyMap<string, Uint8Array> = lowered.bodies,
): string {
  const decoder = new TextDecoder();
  const required = ["agent.instructions", ...definition.contexts.map((item) => item.id)];
  const parts: string[] = [];
  for (const id of required) {
    const segment = lowered.ir.segments.find((item) => item.id === id);
    if (!segment) throw new Error(`cave_context_segment_missing:${id}`);
    const body = bodies.get(segment.bodyHandle);
    if (!body) throw new Error(`cave_context_body_missing:${id}`);
    const text = decoder.decode(body);
    parts.push(id === "agent.instructions" ? text : `<cave-context id=${JSON.stringify(id)}>\n${text}\n</cave-context>`);
  }
  if (definition.output) {
    parts.push(`<cave-output max_tokens=${definition.output.maxTokens}>Return output matching declared schema when present.</cave-output>`);
  }
  if (definition.memory) {
    parts.push("<cave-memory>Use cave_memory_search before relying on prior-session facts. Use cave_memory_remember only for durable facts the user intended to retain.</cave-memory>");
  }
  return parts.join("\n\n");
}

async function applyEfficiencyPlan(
  lowered: LoweredContext,
  plan: CavePlan | undefined,
  engineBin: string | undefined,

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Re-run the lowering pipeline after any change to the agent definition or context files so segments and definition stay in sync
2. Check the error's id: if it names a specific context, verify that context's source file exists and compiles
3. If building LoweredContext manually, ensure every definition.contexts[].id plus agent.instructions has a segment in ir.segments

Example fix

// before
const definition = { contexts: [{ id: "docs.api" }] };
assembleSystemPrompt(definition, lowered); // lowered lacks docs.api

// after
const lowered = await lowerContexts(definition); // regenerate after edits
assembleSystemPrompt(definition, lowered);

function allSegmentsPresent(definition: AgentDefinition, lowered: LoweredContext): boolean {
  const ids = new Set(lowered.ir.segments.map((s) => s.id));
  return ["agent.instructions", ...definition.contexts.map((c) => c.id)]
    .every((id) => ids.has(id));
}

function isContextSegmentMissing(e: unknown): string | null {
  if (!(e instanceof Error)) return null;
  const m = /^cave_context_segment_missing:(.+)$/.exec(e.message);
  return m ? m[1] : null;
}

if (!allSegmentsPresent(definition, lowered)) {
  lowered = await lowerContexts(definition); // regenerate before use
}
await assembleSystemPrompt(definition, lowered);

When it happens

Trigger: definition.contexts references an id that the lowering pass never produced — e.g. the definition was edited after lowering, a context file failed to compile into a segment, or ids were renamed on one side only.

Common situations: Renaming a context id in the agent definition without re-lowering; conditional compilation dropping a context; hand-constructed LoweredContext objects missing segments; version mismatch between definition format and lowering pipeline.

Related errors

• cave_context_body_missing:${id}
• cave_vercel_terminal_failure
• cave_breaker_threshold_invalid
• cave_breaker_retry_requires_budget
• cave_breaker_retry_spend_invalid

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/63e58a3399ca73fc. Report an issue: GitHub.