{"record":{"id":"8e93f89e5e6d8f66","repo":"hashicorp/nomad","slug":"failed-to-decode-0-8-driver-state-v","errorCode":null,"errorMessage":"failed to decode 0.8 driver state: %v","messagePattern":"failed to decode 0\\.8 driver state: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/state/08types.go","lineNumber":130,"sourceCode":"\t// Strip so that it can be unmarshalled\n\tdata := strings.TrimPrefix(t.HandleID, \"DOCKER:\")\n\n\t// The pre09 driver handle ID is given to the driver. It is unmarshalled\n\t// here to check for errors\n\tif _, err := UnmarshalPre09HandleID([]byte(data)); err != nil {\n\t\treturn nil, err\n\t}\n\n\tls.TaskHandle.DriverState = []byte(data)\n\n\treturn ls, nil\n}\n\n// UnmarshalPre09HandleID decodes the pre09 json encoded handle ID\nfunc UnmarshalPre09HandleID(raw []byte) (*TaskRunnerHandle08, error) {\n\tvar handle TaskRunnerHandle08\n\tif err := json.Unmarshal(raw, &handle); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to decode 0.8 driver state: %v\", err)\n\t}\n\n\treturn &handle, nil\n}\n","sourceCodeStart":112,"sourceCodeEnd":135,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/state/08types.go#L112-L135","documentation":"During pre-0.9 to modern state upgrades, UnmarshalPre09HandleID decodes a JSON-encoded 0.8-era driver task handle (TaskRunnerHandle08). This error wraps any json.Unmarshal failure, meaning the stored legacy driver state bytes are not valid JSON or do not match the expected handle schema.","triggerScenarios":"Client startup performs a state Upgrade and calls UnmarshalPre09HandleID on persisted pre-0.9 driver handles; the raw bytes are corrupt, truncated, empty, or were written by an incompatible format, so json.Unmarshal fails.","commonSituations":"Upgrading a very old Nomad client (0.8.x data_dir) whose state files are corrupted or partially written; manually copying/merging data_dir contents; disk corruption or interrupted writes on the legacy state store.","solutions":["Inspect the raw 0.8 driver state file for valid JSON and expected fields (e.g. driver name, handle ID)","If the old task is no longer needed, remove the legacy state entry/data so upgrade skips it","Restore data_dir state files from backup before retrying client start","Check disk health / incomplete writes that may have truncated the state file"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"if len(raw) == 0 || !json.Valid(raw) {\n    return nil, fmt.Errorf(\"skip invalid 0.8 driver state: %d bytes, not valid JSON\", len(raw))\n}","typeGuard":"func isDecodable08Handle(raw []byte) bool {\n    var h TaskRunnerHandle08\n    return json.Unmarshal(raw, &h) == nil\n}","tryCatchPattern":"handle, err := stateimpl.UnmarshalPre09HandleID(raw)\nif err != nil {\n    logger.Warn(\"legacy 0.8 driver state unreadable; skipping restore\", \"err\", err)\n    return nil // degrade gracefully rather than fail client startup\n}","preventionTips":["Back up data_dir before major version upgrades","Do not manually edit or merge legacy state files","Verify disk integrity (fsck/SMART) on hosts storing Nomad state","Plan upgrades along the supported upgrade path rather than skipping many versions with live state"],"tags":["nomad","state-upgrade","json-decode","migration"],"backgroundTag":"legacy-state-decode-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"}