{"record":{"id":"061ea16a18aea4e6","repo":"mastra-ai/mastra","slug":"state-signal-cachekey-is-required","errorCode":null,"errorMessage":"state signal cacheKey is required","messagePattern":"state signal cacheKey is required","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/agent/state-signals.ts","lineNumber":207,"sourceCode":"    contextWindow,\n  };\n}\n\nexport function createStateSignalInput(\n  input: AgentStateSignalInput | (Omit<AgentStateSignalInput, 'id'> & { id?: string }),\n  options?: { defaultId?: string; acceptedAt?: Date },\n): {\n  stateId: string;\n  signal: Extract<CreatedAgentSignal, { type: 'state' }>;\n  mode: 'snapshot' | 'delta';\n  cacheKey: string;\n} {\n  const stateId = input.id ?? options?.defaultId;\n  if (!stateId) {\n    throw new Error('state signal id is required');\n  }\n  if (!input.cacheKey) {\n    throw new Error('state signal cacheKey is required');\n  }\n\n  const mode = input.mode ?? 'snapshot';\n  const { id: _stateId, cacheKey, mode: _mode, value, delta, metadata, ...signalInput } = input;\n  const signal = createSignal({\n    ...signalInput,\n    type: 'state',\n    tagName: signalInput.tagName ?? 'state',\n    acceptedAt: options?.acceptedAt,\n    metadata: {\n      ...metadata,\n      state: {\n        ...(isPlainObject(metadata?.state) ? metadata.state : {}),\n        id: stateId,\n        cacheKey,\n        mode,\n      },\n      ...(value !== undefined ? { value } : {}),","sourceCodeStart":189,"sourceCodeEnd":225,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/agent/state-signals.ts#L189-L225","documentation":"A state signal's cacheKey is what links snapshots/deltas together across turns for versioning and dedupe. createStateSignalInput requires a non-empty cacheKey; an empty string or undefined throws this error right after the id check.","triggerScenarios":"Calling createStateSignalInput where `input.cacheKey` is undefined or '' — e.g. building the input dynamically from a variable that is empty, or destructuring state-signal fields and dropping cacheKey.","commonSituations":"Dynamic cache keys derived from config or entity ids that end up empty; forgetting cacheKey when constructing inputs in tests; typos like `cachekey` leaving the real key undefined.","solutions":["Supply a stable, non-empty cacheKey: `createStateSignalInput({ id: 'doc-state', cacheKey: 'docs:v1', value })`.","Ensure the dynamic source of the cacheKey (entity id, resource id) is populated before the call.","Check property-name typos (`cacheKey` is camelCase) in object literals.","Add a pre-call check: `if (!input.cacheKey) throw ...` or default it from a known constant."],"exampleFix":"// before\ncreateStateSignalInput({ id: 'doc-state', cacheKey: '', value });\n// after\ncreateStateSignalInput({ id: 'doc-state', cacheKey: 'doc:42', value });","handlingStrategy":"validation","validationCode":"if (!input.cacheKey) {\n  throw new TypeError('state signal requires a non-empty cacheKey');\n}","typeGuard":"function hasCacheKey(input: { cacheKey?: string }): input is { cacheKey: string } {\n  return typeof input.cacheKey === 'string' && input.cacheKey.length > 0;\n}","tryCatchPattern":"try {\n  created = createStateSignalInput(input, options);\n} catch (e) {\n  if (e instanceof Error && e.message === 'state signal cacheKey is required') {\n    created = createStateSignalInput({ ...input, cacheKey: deriveCacheKey(input) }, options);\n  } else throw e;\n}","preventionTips":["Derive cacheKey from a stable entity/resource id, not an empty dynamic value","Watch for camelCase typos (`cachekey`/`cache_key` leave the field undefined)","Assert cacheKey presence in tests that build state-signal inputs"],"tags":["signals","state","missing-argument"],"backgroundTag":"missing-required-argument","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}