{"record":{"id":"b478d897e1d643bd","repo":"dagger/dagger","slug":"decode-persisted-directory-payload-unsupported-fo","errorCode":null,"errorMessage":"decode persisted directory payload: unsupported form %q","messagePattern":"decode persisted directory payload: unsupported form %q","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/directory.go","lineNumber":324,"sourceCode":"\tcase persistedDirectoryFormSnapshot:\n\t\tsnapshot, err := loadPersistedImmutableSnapshotByResultID(ctx, dag, resultID, \"directory\", snapshotRole)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\tdir.Snapshot.setValue(snapshot)\n\t\treturn dir, nil\n\tcase persistedDirectoryFormLazy:\n\t\tif persisted.LazyKind == \"\" {\n\t\t\treturn nil, fmt.Errorf(\"decode persisted directory payload: missing lazy kind\")\n\t\t}\n\t\tlazy, err := decodePersistedDirectoryLazy(ctx, dag, persisted.LazyKind, persisted.LazyJSON)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\tdir.Lazy = lazy\n\t\treturn dir, nil\n\tdefault:\n\t\treturn nil, fmt.Errorf(\"decode persisted directory payload: unsupported form %q\", persisted.Form)\n\t}\n}\n\nfunc (*Directory) DecodePersistedObject(ctx context.Context, dag *dagql.Server, resultID uint64, _ *dagql.ResultCall, payload json.RawMessage) (dagql.Typed, error) {\n\treturn decodePersistedDirectoryWithSnapshotRole(ctx, dag, resultID, payload, \"snapshot\")\n}\n\nfunc loadCanonicalScratchDirectory(ctx context.Context) (string, bkcache.ImmutableRef, error) {\n\tquery, err := CurrentQuery(ctx)\n\tif err != nil {\n\t\treturn \"\", nil, fmt.Errorf(\"load canonical scratch directory: %w\", err)\n\t}\n\tscratchSnapshot, err := query.SnapshotManager().Scratch(ctx)\n\tif err != nil {\n\t\treturn \"\", nil, err\n\t}\n\treturn \"/\", scratchSnapshot, nil\n}","sourceCodeStart":306,"sourceCodeEnd":342,"githubUrl":"https://github.com/dagger/dagger/blob/82ba2681dbe30d3547a1dc50ea495900ab5b6047/core/directory.go#L306-L342","documentation":"Thrown when a persisted Directory payload has a Form value the decoder does not recognize (neither snapshot nor lazy). The decoder is a strict state machine over the persisted forms, so any unknown form — typically from a newer or older schema version — is rejected rather than misinterpreted. This protects against silently returning a wrong directory state.","triggerScenarios":"decodePersistedDirectoryWithSnapshotRole reads persisted.Form that is not persistedDirectoryFormSnapshot or persistedDirectoryFormLazy — e.g. empty form field, cache entry written by a different Dagger version with added forms, or corrupt/edited cache data.","commonSituations":"Engine/CLI version skew (payload written by a version with newer forms read by an older decoder); corrupted persisted-result cache; manual cache manipulation.","solutions":["Clear the engine cache and re-run so the directory is re-persisted with a form the current decoder understands","Align engine and CLI versions (the payload schema is version-coupled)","If writing payloads, only emit the registered form constants: \"snapshot\" or \"lazy\""],"exampleFix":"// before\npayload := persistedDirectoryPayload{Form: \"directory_v2\"}\n// after\npayload := persistedDirectoryPayload{Form: \"lazy\", LazyKind: kind, LazyJSON: blob}","handlingStrategy":"validation","validationCode":"var p persistedDirectoryPayload\nif err := json.Unmarshal(payload, &p); err != nil { return err }\nif p.Form != \"snapshot\" && p.Form != \"lazy\" {\n    return fmt.Errorf(\"unknown persisted directory form %q\", p.Form)\n}","typeGuard":"func isKnownDirectoryForm(f string) bool {\n    return f == \"snapshot\" || f == \"lazy\"\n}","tryCatchPattern":null,"preventionTips":["Only emit registered form constants when persisting","Version-stamp persisted payloads and reject unknown versions early","Clear stale caches after upgrading the engine"],"tags":["serialization","cache","version-skew","directory"],"backgroundTag":"unsupported-payload-form","analyzedSha":"82ba2681dbe30d3547a1dc50ea495900ab5b6047","analyzedAt":"2026-09-05T07:21:37.930Z","contentChangedAt":"2026-09-05T07:21:37.930Z","schemaVersion":2},"datasetVersion":"2026-09-12T12:17:11.808Z"}