withastro/astro · error · AstroError
SessionStorageSaveError
SessionStorageSaveError
Error message
The session key was not provided.
What it means
AstroSession.set requires a non-empty key string. It throws AstroError code SessionStorageSaveError when the provided key is falsy (empty string or undefined), before any serialization happens.
Source
Thrown at packages/astro/src/core/session/runtime.ts:185
}
this.#dirty = true;
}
/**
* Sets a session value. The session is created if it does not exist.
*/
set<T = void, K extends string = keyof App.SessionData | (string & {})>(
key: K,
value: T extends void
? K extends keyof App.SessionData
? App.SessionData[K]
: any
: NoInfer<T>,
{ ttl }: { ttl?: number } = {},
) {
if (!key) {
throw new AstroError({
...SessionStorageSaveError,
message: 'The session key was not provided.',
});
}
// save a clone of the passed in object so later updates are not
// persisted into the store. Attempting to serialize also allows
// us to throw an error early if needed.
let cloned: T;
try {
cloned = unflatten(JSON.parse(stringify(value)));
} catch (err) {
throw new AstroError(
{
...SessionStorageSaveError,
message: `The session data for ${key} could not be serialized.`,
hint: 'See the devalue library for all supported types: https://github.com/rich-harris/devalue',
},
{ cause: err },View on GitHub (pinned to d081033d5f)
Solutions
- Validate the key is a non-empty string before calling set.
- Default missing keys to a stable non-empty identifier.
- Log/guard dynamic keys at the call site.
Example fix
// before Astro.session.set(userInput, data); // after const key = userInput || 'guest'; Astro.session.set(key, data);
Defensive patterns
Strategy: type-guard
Validate before calling
function sessionSet(session, key, value) {
if (typeof key !== 'string' || key.length === 0) {
throw new Error('session.set requires a non-empty string key');
}
return session.set(key, value);
} Type guard
const isValidSessionKey = (key: unknown): key is string => typeof key === 'string' && key.length > 0;
Prevention
- Never derive a session key from untrusted input without a fallback.
- Default computed keys to a stable non-empty string.
- Wrap session.set in a helper that validates the key.
When it happens
Trigger: Calling `Astro.session.set('', value)` or `Astro.session.set(someVar, value)` where someVar resolved to undefined or ''.
Common situations: Using a computed key from params/query that is missing; destructuring a value that is undefined; defaulting a key to ''.
Related errors
AI-assisted analysis of withastro/astro@d081033d5f (2026-08-12).
Data as JSON: /api/errors/4433ccd94ead7e99.
Report an issue: GitHub.