@k8ordo/state

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.

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.

k8ordo

React libraries that use Baseline features without holding back.