{"record":{"id":"dcfc9ffe6d70a276","repo":"apify/crawlee","slug":"statevalidationerror-persiststatekey-result-issue","errorCode":null,"errorMessage":"StateValidationError(persistStateKey, result.issues)","messagePattern":"StateValidationError\\(persistStateKey, result\\.issues\\)","errorType":"validation","errorClass":"StateValidationError","httpStatus":null,"severity":"error","filePath":"packages/core/src/recoverable_state.ts","lineNumber":52,"sourceCode":"export function convertStateSync<TFrom, TTo>(\n    conversion: SyncStateConversion<TFrom, TTo>,\n    value: TFrom,\n    persistStateKey: string,\n): TTo {\n    if (typeof conversion === 'function') {\n        return conversion(value);\n    }\n\n    const result = conversion['~standard'].validate(value);\n\n    if ('then' in result) {\n        throw new Error(\n            `The state conversion for '${persistStateKey}' validated asynchronously, which this caller cannot await.`,\n        );\n    }\n\n    if (result.issues) {\n        throw new StateValidationError(persistStateKey, result.issues);\n    }\n\n    return result.value;\n}\n\nexport interface RecoverableStatePersistenceOptions {\n    /**\n     * The key under which the state is stored in the KeyValueStore\n     */\n    persistStateKey: string;\n\n    /**\n     * Flag to enable or disable state persistence\n     */\n    persistenceEnabled?: boolean;\n\n    /**\n     * The KeyValueStore to persist into, defaulting to the default store. Accepts a pending","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/apify/crawlee/blob/dbe57fb09ca607ad59dcf998f3925ef9ac3bb26c/packages/core/src/recoverable_state.ts#L34-L70","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nconst state = recoverableState.convertStateSync(rawPersisted);\n// after\nconst parsed = mySchema.safeParse(rawPersisted);\nconst state = recoverableState.convertStateSync(parsed.success ? parsed.data : defaults);","handlingStrategy":"validation","validationCode":"const result = schema['~standard'].validate(value);\nif (result instanceof Promise) throw new Error('Schema must validate synchronously for convertStateSync');\nif (result.issues) throw new StateValidationError(key, result.issues);","typeGuard":"function hasIssues(r): r is { issues: unknown[] } { return r != null && 'issues' in r && r.issues != null; }","tryCatchPattern":"try {\n  const value = state.convertStateSync(raw);\n} catch (err) {\n  if (err instanceof StateValidationError) {\n    console.error(`Invalid state for ${err.key}:`, err.issues);\n    return defaults;\n  }\n  throw err;\n}","preventionTips":["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"],"tags":["validation","state","schema"],"backgroundTag":"schema-validation-failed","analyzedSha":"dbe57fb09ca607ad59dcf998f3925ef9ac3bb26c","analyzedAt":"2026-08-30T22:22:28.328Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}