{"record":{"id":"026fb63dac57ce15","repo":"withastro/astro","slug":"the-passed-value-can-t-be-serialized","errorCode":null,"errorMessage":"The passed value can't be serialized.","messagePattern":"The passed value can't be serialized\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/astro/src/core/middleware/index.ts","lineNumber":205,"sourceCode":"\treturn proto === baseProto;\n}\n\n/**\n * It attempts to serialize `value` and return it as a string.\n *\n * ## Errors\n *  If the `value` is not serializable if the function will throw a runtime error.\n *\n * Something is **not serializable** when it contains properties/values like functions, `Map`, `Set`, `Date`,\n * and other types that can't be made a string.\n *\n * @param value\n */\nfunction trySerializeLocals(value: unknown) {\n\tif (isLocalsSerializable(value)) {\n\t\treturn JSON.stringify(value);\n\t} else {\n\t\tthrow new Error(\"The passed value can't be serialized.\");\n\t}\n}\n\n// NOTE: this export must export only the functions that will be exposed to user-land as officials APIs\nexport { createContext, sequence, trySerializeLocals };\nexport { defineMiddleware } from './defineMiddleware.js';\n","sourceCodeStart":187,"sourceCodeEnd":212,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/astro/src/core/middleware/index.ts#L187-L212","documentation":"Thrown by trySerializeLocals when the locals value contains non-serializable types. Locals are serialized (JSON.stringify) for transmission to client components or across the SSR boundary; types like functions, Map, Set, Date, class instances, or circular references break JSON.stringify and are rejected up front by isLocalsSerializable.","triggerScenarios":"Assigning functions, Map, Set, Date, class instances, Symbols, or circular references to Astro.locals/context.locals, then triggering serialization (e.g. passing locals to client islands, server actions, or an adapter that serializes state). trySerializeLocals runs isLocalsSerializable and throws a plain Error if it returns false.","commonSituations":"Storing a class instance or a DB connection in locals; putting Map/Set collections in locals; assigning a function/callback to locals; circular object graphs from ORMs or session objects.","solutions":["Store only plain serializable data (primitives, plain objects, arrays) in locals.","Convert Map/Set to plain objects/arrays before storing; serialize Date to ISO strings.","Move non-serializable resources (connections, functions) to a module-level cache or Symbol keyed property that serialization skips."],"exampleFix":"// before\nAstro.locals.session = userSession; // class instance\nAstro.locals.roles = new Set(['admin']);\n\n// after\nAstro.locals.session = { userId: userSession.userId };\nAstro.locals.roles = ['admin'];","handlingStrategy":"type-guard","validationCode":"// Validate serializability before storing.\nfunction isSerializable(v: unknown): boolean {\n  if (v === null || ['string','number','boolean'].includes(typeof v)) return true;\n  if (Array.isArray(v)) return v.every(isSerializable);\n  if (typeof v === 'object') {\n    return Object.values(v).every(isSerializable);\n  }\n  return false; // functions, Map, Set, Date, Symbol, undefined\n}\nif (!isSerializable(value)) throw new Error('not serializable');\nAstro.locals.data = value;","typeGuard":"function isLocalsSerializable(value: unknown): boolean {\n  if (value === null) return true;\n  const t = typeof value;\n  if (t === 'function' || t === 'symbol' || t === 'undefined') return false;\n  if (t !== 'object') return true;\n  if (value instanceof Map || value instanceof Set || value instanceof Date) return false;\n  return Object.values(value).every(isLocalsSerializable);\n}","tryCatchPattern":"try {\n  trySerializeLocals(Astro.locals);\n} catch (e) {\n  if (e instanceof Error && /can't be serialized/i.test(e.message)) {\n    // strip non-serializable values from locals\n  } else throw e;\n}","preventionTips":["Store only plain JSON-safe data in locals.","Convert Map/Set to plain objects/arrays and Date to ISO strings before storing.","Keep DB connections/functions on module-scoped caches, not in locals."],"tags":["locals","serialization","json","state"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}