{"record":{"id":"63e58a3399ca73fc","repo":"JuliusBrussee/caveman","slug":"cave-context-segment-missing-id","errorCode":null,"errorMessage":"cave_context_segment_missing:${id}","messagePattern":"cave_context_segment_missing:(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/agent/src/runtime.ts","lineNumber":2586,"sourceCode":"    [\"results_artifacts\", (bill.artifact ?? 0) + (bill.skill ?? 0) + (bill.tool_result ?? 0)],\n    [\"output\", outputMaxTokens],\n  ];\n  for (const [slot, used] of slots) {\n    if (used > plan.budgets[slot]) throw new Error(`cave_${slot}_budget_exceeded`);\n  }\n}\n\nexport function assembleSystemPrompt(\n  definition: AgentDefinition,\n  lowered: LoweredContext,\n  bodies: ReadonlyMap<string, Uint8Array> = lowered.bodies,\n): string {\n  const decoder = new TextDecoder();\n  const required = [\"agent.instructions\", ...definition.contexts.map((item) => item.id)];\n  const parts: string[] = [];\n  for (const id of required) {\n    const segment = lowered.ir.segments.find((item) => item.id === id);\n    if (!segment) throw new Error(`cave_context_segment_missing:${id}`);\n    const body = bodies.get(segment.bodyHandle);\n    if (!body) throw new Error(`cave_context_body_missing:${id}`);\n    const text = decoder.decode(body);\n    parts.push(id === \"agent.instructions\" ? text : `<cave-context id=${JSON.stringify(id)}>\\n${text}\\n</cave-context>`);\n  }\n  if (definition.output) {\n    parts.push(`<cave-output max_tokens=${definition.output.maxTokens}>Return output matching declared schema when present.</cave-output>`);\n  }\n  if (definition.memory) {\n    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>\");\n  }\n  return parts.join(\"\\n\\n\");\n}\n\nasync function applyEfficiencyPlan(\n  lowered: LoweredContext,\n  plan: CavePlan | undefined,\n  engineBin: string | undefined,","sourceCodeStart":2568,"sourceCodeEnd":2604,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/27d5a3981a347890211bb1bf2439e5c821a63bc9/packages/agent/src/runtime.ts#L2568-L2604","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Re-run the lowering pipeline after any change to the agent definition or context files so segments and definition stay in sync","Check the error's id: if it names a specific context, verify that context's source file exists and compiles","If building LoweredContext manually, ensure every definition.contexts[].id plus agent.instructions has a segment in ir.segments"],"exampleFix":"// before\nconst definition = { contexts: [{ id: \"docs.api\" }] };\nassembleSystemPrompt(definition, lowered); // lowered lacks docs.api\n\n// after\nconst lowered = await lowerContexts(definition); // regenerate after edits\nassembleSystemPrompt(definition, lowered);","handlingStrategy":"validation","validationCode":"function allSegmentsPresent(definition: AgentDefinition, lowered: LoweredContext): boolean {\n  const ids = new Set(lowered.ir.segments.map((s) => s.id));\n  return [\"agent.instructions\", ...definition.contexts.map((c) => c.id)]\n    .every((id) => ids.has(id));\n}","typeGuard":"function isContextSegmentMissing(e: unknown): string | null {\n  if (!(e instanceof Error)) return null;\n  const m = /^cave_context_segment_missing:(.+)$/.exec(e.message);\n  return m ? m[1] : null;\n}","tryCatchPattern":"if (!allSegmentsPresent(definition, lowered)) {\n  lowered = await lowerContexts(definition); // regenerate before use\n}\nawait assembleSystemPrompt(definition, lowered);","preventionTips":["Always re-lower after editing agent definitions or context files","Never hand-assemble LoweredContext without covering every referenced id","Treat segment id renames as breaking changes and update both sides atomically"],"tags":["context","lowering","configuration"],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}