{"record":{"id":"1833087ba661513a","repo":"mantinedev/mantine","slug":"mantine-hooks-hookname-failed-to-serialize-th","errorCode":null,"errorMessage":"@mantine/hooks ${hookName}: Failed to serialize the value","messagePattern":"@mantine/hooks (.+?): Failed to serialize the value","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/@mantine/hooks/src/use-local-storage/create-storage.ts","lineNumber":31,"sourceCode":"\n  /** If set to true, value will be updated in useEffect after mount. Default value is true. */\n  getInitialValueInEffect?: boolean;\n\n  /** Determines whether the value must be synced between browser tabs, `true` by default */\n  sync?: boolean;\n\n  /** Function to serialize value into string to be save in storage */\n  serialize?: (value: T) => string;\n\n  /** Function to deserialize string value from storage to value */\n  deserialize?: (value: string | undefined) => T;\n}\n\nfunction serializeJSON<T>(value: T, hookName: string = 'use-local-storage') {\n  try {\n    return JSON.stringify(value);\n  } catch (error) {\n    throw new Error(`@mantine/hooks ${hookName}: Failed to serialize the value`);\n  }\n}\n\nfunction deserializeJSON(value: string | undefined) {\n  try {\n    return value && JSON.parse(value);\n  } catch {\n    return value;\n  }\n}\n\nfunction createStorageHandler(type: StorageType) {\n  const getItem = (key: string) => {\n    try {\n      return window[type].getItem(key);\n    } catch (error) {\n      console.warn('use-local-storage: Failed to get value from storage, localStorage is blocked');\n      return null;","sourceCodeStart":13,"sourceCodeEnd":49,"githubUrl":"https://github.com/mantinedev/mantine/blob/8a284e2c2c53a9cb6f39f5dc389bf41b7a2073f8/packages/@mantine/hooks/src/use-local-storage/create-storage.ts#L13-L49","documentation":"The use-local-storage family of hooks (useLocalStorage, useLocalStorageWithNativeEvents, useDebouncedValue users of createStorage, useSessionStorage) JSON.stringify values before writing them. If the value contains something non-serializable (circular references, BigInt, functions), stringification fails and this wrapper error is thrown.","triggerScenarios":"Storing an object with a circular reference (e.g. a DOM node, class instance with back-references); storing BigInt values; storing functions or class instances like dayjs objects with cyclic internals.","commonSituations":"Caching React refs or DOM elements; persisting ORM/model instances or dayjs/Date-like objects with cycles; JSON.stringify quirks with BigInt after a schema change to include ids as BigInt.","solutions":["Store a serializable plain representation: convert dates to ISO strings, break circular references, stringify BigInts","Use a custom serializer or write a toStorage/fromStorage wrapper that safely transforms the value","If the value is inherently non-serializable, keep it in state/memory instead of localStorage"],"exampleFix":"// before\nuseLocalStorage({ key: 'node', value: someDomNode }); // circular\n\n// after\nuseLocalStorage({ key: 'tag', value: { id: 1, name: 'x' } }); // plain serializable object","handlingStrategy":"validation","validationCode":"function isSerializable(value: unknown): boolean {\n  try {\n    JSON.stringify(value);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nif (!isSerializable(value)) {\n  // store a simplified copy instead\n}","typeGuard":"function isPlainSerializable(v: unknown): boolean {\n  return (\n    v === null ||\n    ['string', 'number', 'boolean'].includes(typeof v) ||\n    (Array.isArray(v) && v.every(isPlainSerializable)) ||\n    (typeof v === 'object' &&\n      Object.values(v).every((x) => x !== undefined && !BigUint64Array && typeof x !== 'function') &&\n      Object.values(v).every(isPlainSerializable))\n  );\n}","tryCatchPattern":null,"preventionTips":["Store plain JSON data (strings, numbers, booleans, arrays, plain objects) only","Convert dates to ISO strings and BigInt to string before persisting","Never store DOM nodes, class instances, or objects with cycles in localStorage hooks"],"tags":["local-storage","serialization","json","use-local-storage"],"backgroundTag":"json-serialization-failed","analyzedSha":"8a284e2c2c53a9cb6f39f5dc389bf41b7a2073f8","analyzedAt":"2026-08-28T10:25:51.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}