{"record":{"id":"9a7a9311a2e792d5","repo":"hashicorp/nomad","slug":"failed-to-create-fsm-w","errorCode":null,"errorMessage":"failed to create FSM: %w","messagePattern":"failed to create FSM: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"helper/raftutil/snapshot.go","lineNumber":24,"sourceCode":"import (\n\t\"fmt\"\n\t\"io\"\n\t\"os\"\n\n\t\"github.com/hashicorp/go-hclog\"\n\t\"github.com/hashicorp/nomad/helper/snapshot\"\n\t\"github.com/hashicorp/nomad/nomad\"\n\t\"github.com/hashicorp/nomad/nomad/state\"\n\t\"github.com/hashicorp/nomad/nomad/structs\"\n\t\"github.com/hashicorp/raft\"\n)\n\nfunc RestoreFromArchive(archive io.Reader, filter *nomad.FSMFilter) (raft.FSM, *state.StateStore, *raft.SnapshotMeta, error) {\n\tlogger := hclog.L()\n\n\tfsm, err := dummyFSM(logger)\n\tif err != nil {\n\t\treturn nil, nil, nil, fmt.Errorf(\"failed to create FSM: %w\", err)\n\t}\n\n\t// r is closed by RestoreFiltered, w is closed by CopySnapshot\n\tr, w := io.Pipe()\n\n\terrCh := make(chan error)\n\tmetaCh := make(chan *raft.SnapshotMeta)\n\n\tgo func() {\n\t\tmeta, err := snapshot.CopySnapshot(archive, w)\n\t\tif err != nil {\n\t\t\terrCh <- fmt.Errorf(\"failed to read snapshot: %w\", err)\n\t\t} else {\n\t\t\tmetaCh <- meta\n\t\t}\n\t}()\n\n\terr = fsm.RestoreWithFilter(r, filter)","sourceCodeStart":6,"sourceCodeEnd":42,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/helper/raftutil/snapshot.go#L6-L42","documentation":"RestoreFromArchive first constructs a dummy Nomad FSM that will ingest the snapshot archive. If dummyFSM fails to create that FSM, the function aborts with \"failed to create FSM: %w\". This happens before any snapshot bytes are read, so the archive itself is not the cause — FSM construction (internal state store setup) failed.","triggerScenarios":"Calling RestoreFromArchive (directly or via RedactSnapshot / NewHarnessFromSnapshot / the nomad-snapshot Run command) when dummyFSM returns an error from its internal state.NewStateStore or similar setup failure.","commonSituations":"Running the tool in an environment where the state store cannot initialize (e.g. missing working directory, memory/resources constraints); a build/version mismatch where the FSM constructor depends on misconfigured logger or schema initialization.","solutions":["Inspect the wrapped cause (%w) in the message — fix the underlying dummyFSM/state-store initialization error it reports.","Rebuild the tool from the same Nomad version as the snapshot to avoid schema-init incompatibilities.","Retry in a normal writable environment (ensure TMPDIR/working dir exists and is writable) if the store needs temp files.","If transient (resource exhaustion), retry with adequate memory."],"exampleFix":"// before: state store init fails because working dir is missing\nsnap, err := os.Open(\"snap.tar\") // then RestoreFromArchive -> \"failed to create FSM: ...\"\n// after: ensure a valid writable working environment first\nif err := os.MkdirAll(workDir, 0o755); err != nil { log.Fatal(err) }\nfsm, store, meta, err := raftutil.RestoreFromArchive(snap, nil)","handlingStrategy":"try-catch","validationCode":"// Sanity-check the environment before restoring\nif fi, err := os.Stat(\".\"); err != nil || !fi.IsDir() {\n    return fmt.Errorf(\"working directory unavailable\")\n}","typeGuard":null,"tryCatchPattern":"fsm, store, meta, err := raftutil.RestoreFromArchive(archive, filter)\nif err != nil {\n    if strings.Contains(err.Error(), \"failed to create FSM\") {\n        return fmt.Errorf(\"environment/FSM init failed (not a snapshot problem): %w\", err)\n    }\n    return err\n}","preventionTips":["Run the snapshot tool in an environment with a writable working directory and adequate memory.","Match the tool's Nomad version to the cluster that produced the snapshot.","Read the wrapped cause first — this error always indicates FSM construction, never archive contents.","Pin the tool binary version in automation to avoid schema-init drift."],"tags":["fsm","snapshot","initialization"],"backgroundTag":"fsm-init-failed","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}