Troubleshooting
Common symptoms, their causes and their fixes. To look up an error, search this page for its wording.
On this page
fields must tolerate absence
Cause
A field has neither .default() nor .optional(). A URL parameter or a stored value can always be missing, so the definition throws as the module loads.
Fix
Add .default() or .optional() to the fields the error names (z._default() or z.optional() in zod/mini). If the error says rejects its own defaults, make the object-level .refine() accept the all-defaults value.
url boolean fields must use z.stringbool()
Cause
A url field or array item is z.boolean() or z.coerce.boolean(). Neither reads the URL’s "false" as false, so the definition throws as the module loads.
Fix
Use z.stringbool().
url array fields must default to []
Cause
A url array is .optional() or defaults to something other than []. A URL without the parameter and a URL written with an empty array are the same. Unless the default is [], an empty array can never be written.
Fix
Give it .default([]).
href not callable in a Server Component
Cause
The definition is exported from a 'use client' file. A Server Component receives a client reference in its place, so href and parseUrl are not there to call.
Fix
Move the definition to a module without 'use client'. The definition is pure, so both the server and the client can import it.
has no URL serialization
Cause
A value no URL can hold, such as a Date, is being written to a url field.
Fix
Keep url fields to strings, numbers, booleans and arrays of them. Hold a date as a string.
Full page reload on update()
Cause
The router does not intercept Navigation API navigations. Next.js today is one, and there navigation.navigate() is a full page load.
Fix
Under that router, change the URL with links and GET forms. @k8ordo/framework runs on @k8ordo/router, where it is never a full page load.
A boolean that resets on every write
Cause
The schema of entry, Web Storage or a cookie uses z.stringbool(). In those places the written true reaches the schema as a boolean. z.stringbool() accepts only a string, so it rejects that true and the field falls back to its default.
Fix
Use z.boolean(). A field moved from url to entry needs the same change.
A date that resets after a reload
Cause
Web Storage and cookie values are stored as JSON. A Date comes back as a string, which z.date() rejects, so the field falls back to its default. The Date shows right after the write because update() applies the value without going through JSON.
Fix
Keep the field to a type JSON can hold. Hold a date as a string.
Two states with the same values
Cause
Two definitions of the same kind use the same key, and so share one store. @k8ordo/color-scheme also defines a local state under the key color-scheme.
Fix
Change the key to a name nothing else in the app uses. Renaming the key renames the stored data, so values saved under the old key are no longer read.
A cookie Safari drops
Cause
The Cookie Store API always sets Secure, and Safari drops a Secure cookie even on http://localhost.
Fix
Serve over HTTPS during development too.
Values leaking between tests
Cause
Stores stay in the module’s registry, and stored values stay in the browser.
Fix
Unmount the components, then call resetStateRegistry(). After that, delete the stored values by storageKey or cookieName.
Navigation away during a test
Cause
Nothing intercepts the navigate event, so navigation.navigate() is a full page load.
Fix
Intercept the navigate event in the test itself, calling event.intercept() as a router would.