{"record":{"id":"4d09f97b8808e1bd","repo":"JuliusBrussee/caveman","slug":"caveman-agent-context-id-is-required","errorCode":null,"errorMessage":"caveman agent: context id is required","messagePattern":"caveman agent: context id is required","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/agent/src/primitives.ts","lineNumber":348,"sourceCode":"  readonly privacy: PrivacyClass;\n  readonly opaque: boolean;\n  readonly ttlTurns?: number;\n}\n\nexport function context(options: {\n  id: string;\n  kind: ContextKind;\n  source: string | FileSource;\n  stability: ContextStability;\n  safety?: SafetyClass;\n  priority?: ContextPriority;\n  recovery?: RecoveryKind;\n  cacheRegion?: CacheRegion;\n  privacy?: PrivacyClass;\n  opaque?: boolean;\n  ttlTurns?: number;\n}): ContextDefinition {\n  if (options.id.trim() === \"\") throw new Error(\"caveman agent: context id is required\");\n  if (options.ttlTurns !== undefined && (!Number.isSafeInteger(options.ttlTurns) || options.ttlTurns <= 0)) {\n    throw new Error(\"caveman agent: context ttlTurns must be a positive integer\");\n  }\n  const definition: ContextDefinition = {\n    kind: \"context\",\n    id: options.id,\n    segmentKind: options.kind,\n    source: options.source,\n    stability: options.stability,\n    safety: options.safety ?? \"S0\",\n    priority: options.priority ?? \"required\",\n    recovery: options.recovery ?? \"none\",\n    cacheRegion: options.cacheRegion ?? (options.stability === \"build\" ? \"frozen_prefix\" : \"live_zone\"),\n    privacy: options.privacy ?? \"local_sensitive\",\n    opaque: options.opaque ?? false,\n    ...(options.ttlTurns === undefined ? {} : { ttlTurns: options.ttlTurns }),\n  };\n  return Object.freeze(definition);","sourceCodeStart":330,"sourceCodeEnd":366,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/agent/src/primitives.ts#L330-L366","documentation":"The context() primitive requires a non-blank options.id, which names the context definition. An id that is empty or consists only of whitespace (the check trims before comparing) is rejected. Context ids must identify the definition, so an empty id would produce an unusable, unaddressable context.","triggerScenarios":"Calling context() with id: \"\" or id: \"   \", or with an id computed from an empty variable (e.g. process.env.CONTEXT_ID unset yields \"\"), or with a template/prompt-derived id that trimmed down to nothing.","commonSituations":"An env var or config field feeding the id is missing or blank; a dynamic id built by joining/trimming other fields ends up empty; forgetting to pass id entirely in loosely-typed call sites.","solutions":["Pass a non-empty, non-whitespace id string to context(), e.g. context({ id: \"session-main\", ... })","If the id comes from an env var or config, default it: id = process.env.CONTEXT_ID || \"default-context\"","Validate/trim the id before construction and throw a domain-specific error if blank","Fix upstream string construction (joins, trims, slicing) that can produce an empty id"],"exampleFix":"// before\nconst id = process.env.CONTEXT_ID ?? \"\"; // unset -> \"\"\ncontext({ id, ttlTurns: 10 });\n// after\nconst id = process.env.CONTEXT_ID?.trim() || \"default-context\";\ncontext({ id, ttlTurns: 10 });","handlingStrategy":"validation","validationCode":"function isValidContextId(id) {\n  return typeof id === \"string\" && id.trim() !== \"\";\n}\n// before calling: if (!isValidContextId(id)) throw new Error(`bad context id: ${JSON.stringify(id)}`);","typeGuard":"function isNonEmptyString(v: unknown): v is string {\n  return typeof v === \"string\" && v.trim() !== \"\";\n}","tryCatchPattern":"try {\n  const def = context({ id, ttlTurns });\n} catch (err) {\n  if (err instanceof Error && err.message.includes(\"context id is required\")) {\n    console.error(`Invalid context id ${JSON.stringify(id)}: provide a non-blank string`);\n    return;\n  }\n  throw err;\n}","preventionTips":["Default env/config-derived ids: id = rawId?.trim() || \"default-context\"","Validate ids at config-load time, not at construction time only","Type context options with a branded non-empty string type where practical","Add a unit test asserting context({ id: \"\" }) and context({ id: \"  \" }) both throw"],"tags":["validation","configuration","typescript","context"],"backgroundTag":"empty-required-field","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}