{"record":{"id":"4566b31100cfe907","repo":"mastra-ai/mastra","slug":"observability-invalid-delta-cursor","errorCode":"OBSERVABILITY_INVALID_DELTA_CURSOR","errorMessage":"Invalid observability delta cursor","messagePattern":"Invalid observability delta cursor","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"warning","filePath":"packages/core/src/storage/domains/observability/inmemory.ts","lineNumber":223,"sourceCode":"      const cursorId = cursorIds.get(previous);\n      cursorIds.delete(previous);\n      records[existingIndex] = record;\n      if (cursorId !== undefined) {\n        cursorIds.set(record, cursorId);\n      }\n      return;\n    }\n    records.push(record);\n    cursorIds.set(record, this.allocateObservabilityCursorId());\n  }\n\n  private encodeDeltaCursor(cursorId?: number | null): string {\n    return (cursorId ?? 0).toString();\n  }\n\n  private decodeDeltaCursor(cursor: string): number {\n    if (!/^\\d+$/.test(cursor)) {\n      throw new MastraError({\n        id: 'OBSERVABILITY_INVALID_DELTA_CURSOR',\n        domain: ErrorDomain.MASTRA_OBSERVABILITY,\n        category: ErrorCategory.USER,\n        text: 'Invalid observability delta cursor',\n      });\n    }\n\n    const cursorId = Number.parseInt(cursor, 10);\n    if (!Number.isInteger(cursorId) || cursorId < 0) {\n      throw new MastraError({\n        id: 'OBSERVABILITY_INVALID_DELTA_CURSOR',\n        domain: ErrorDomain.MASTRA_OBSERVABILITY,\n        category: ErrorCategory.USER,\n        text: 'Invalid observability delta cursor',\n      });\n    }\n\n    return cursorId;","sourceCodeStart":205,"sourceCodeEnd":241,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/storage/domains/observability/inmemory.ts#L205-L241","documentation":"decodeDeltaCursor validates the string form of an observability delta cursor: it must be all digits. A cursor failing the /^\\d+$/ regex (empty string, letters, base64 blob, negative sign) indicates corruption or a cursor produced by a different mechanism, so this USER-category error is thrown.","triggerScenarios":"Calling afterCursorId (directly or via a delta-polling list method) with a malformed cursor string — empty, non-numeric, truncated, or from another storage backend's cursor format.","commonSituations":"Persisting cursors to a store/file and mangling them; passing a cursor from a different provider (DB cursors are not numeric strings); hand-crafting cursors in tests or scripts; stale clients after a cursor format change.","solutions":["Only pass cursors obtained from a previous response of the same storage instance; never hand-construct them.","Reset the poller's cursor (start from the beginning / undefined cursor) when an invalid cursor is detected.","Validate cursor format before sending if cursors cross process/serialization boundaries (e.g. base64-encoded payloads).","Clear stale cursor state in your job/store if the backend was switched or the format changed."],"exampleFix":"// before\nconst page = await storage.listMetrics({ cursor: lastCursor ?? 'abc' }); // throws\n\n// after\nconst page = await storage.listMetrics({ cursor: isValidNumericCursor(lastCursor) ? lastCursor : undefined });","handlingStrategy":"validation","validationCode":"const isValidDeltaCursor = (c: unknown): c is string => typeof c === 'string' && /^\\d+$/.test(c);\nif (cursor !== undefined && !isValidDeltaCursor(cursor)) cursor = undefined; // restart from beginning","typeGuard":"function isValidDeltaCursor(c: unknown): c is string {\n  return typeof c === 'string' && /^\\d+$/.test(c);\n}","tryCatchPattern":"try {\n  page = await storage.listLogs({ cursor });\n} catch (e) {\n  if ((e as MastraError).id === 'OBSERVABILITY_INVALID_DELTA_CURSOR') {\n    cursor = undefined;\n    page = await storage.listLogs({}); // reset cursor, restart polling\n  } else throw e;\n}","preventionTips":["Only reuse cursors verbatim from the same storage provider's responses.","Never persist cursors through transformations that can alter format.","Clear stored cursor state when switching storage backends.","Validate cursor strings before sending them across service boundaries."],"tags":["storage","observability","cursor","validation"],"backgroundTag":"invalid-cursor","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}