apify/crawlee · error · StateValidationError

StateValidationError(persistStateKey, result.issues)

Error message

StateValidationError(persistStateKey, result.issues)

What it means

StateValidationError is thrown by convertStateSync when the schema validator reports issues for the value being converted under a given persistence key. This is the synchronous conversion path, which cannot run async validation, so a schema that validates asynchronously is rejected outright with a separate error. Here the conversion ran but the validated result contained issues, meaning the state value does not match the declared schema.

Source

Thrown at packages/core/src/recoverable_state.ts:52

export function convertStateSync<TFrom, TTo>(
    conversion: SyncStateConversion<TFrom, TTo>,
    value: TFrom,
    persistStateKey: string,
): TTo {
    if (typeof conversion === 'function') {
        return conversion(value);
    }

    const result = conversion['~standard'].validate(value);

    if ('then' in result) {
        throw new Error(
            `The state conversion for '${persistStateKey}' validated asynchronously, which this caller cannot await.`,
        );
    }

    if (result.issues) {
        throw new StateValidationError(persistStateKey, result.issues);
    }

    return result.value;
}

export interface RecoverableStatePersistenceOptions {
    /**
     * The key under which the state is stored in the KeyValueStore
     */
    persistStateKey: string;

    /**
     * Flag to enable or disable state persistence
     */
    persistenceEnabled?: boolean;

    /**
     * The KeyValueStore to persist into, defaulting to the default store. Accepts a pending

View on GitHub (pinned to dbe57fb09c)

Solutions

Inspect result.issues in the error to see which fields failed validation
Update the persisted state in the KeyValueStore to match the current schema, or delete the key so defaults are used
Loosen the schema (add defaults/optional fields) to accept legacy persisted state
Add a migration/transform before validation so old shapes are converted to the new schema

Example fix

// before
const state = recoverableState.convertStateSync(rawPersisted);
// after
const parsed = mySchema.safeParse(rawPersisted);
const state = recoverableState.convertStateSync(parsed.success ? parsed.data : defaults);

Defensive patterns

Strategy: validation

Validate before calling

const result = schema['~standard'].validate(value);
if (result instanceof Promise) throw new Error('Schema must validate synchronously for convertStateSync');
if (result.issues) throw new StateValidationError(key, result.issues);

Type guard

function hasIssues(r): r is { issues: unknown[] } { return r != null && 'issues' in r && r.issues != null; }

Try / catch

try {
  const value = state.convertStateSync(raw);
} catch (err) {
  if (err instanceof StateValidationError) {
    console.error(`Invalid state for ${err.key}:`, err.issues);
    return defaults;
  }
  throw err;
}

Prevention

Validate persisted data against the schema before passing to convertStateSync
Version your persisted state and write migrations for schema changes
Keep synchronous-only schemas for the sync conversion path
Fall back to defaults when stored state fails validation

When it happens

Trigger: Calling convertStateSync with a value that fails the schema's '~standard'.validate, e.g. persisted state loaded from a KeyValueStore that no longer matches the current schema.

Common situations: Schema was tightened after state was already persisted under the key; manual edits or older app versions wrote state that fails current validation; deserialized JSON lacks required fields.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

AI-assisted analysis of apify/crawlee@dbe57fb09c (2026-08-30). Data as JSON: /api/errors/dcfc9ffe6d70a276. Report an issue: GitHub.