{"record":{"id":"3a95c1c7b18d943c","repo":"hashicorp/nomad","slug":"failed-to-decode-taskconfig-state-from-handle-v","errorCode":null,"errorMessage":"failed to decode taskConfig state from handle: %v","messagePattern":"failed to decode taskConfig state from handle: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"drivers/java/driver.go","lineNumber":395,"sourceCode":"\nfunc (d *Driver) RecoverTask(handle *drivers.TaskHandle) error {\n\tif handle == nil {\n\t\treturn fmt.Errorf(\"handle cannot be nil\")\n\t}\n\n\t// If already attached to handle there's nothing to recover.\n\tif _, ok := d.tasks.Get(handle.Config.ID); ok {\n\t\td.logger.Debug(\"nothing to recover; task already exists\",\n\t\t\t\"task_id\", handle.Config.ID,\n\t\t\t\"task_name\", handle.Config.Name,\n\t\t)\n\t\treturn nil\n\t}\n\n\tvar taskState TaskState\n\tif err := handle.GetDriverState(&taskState); err != nil {\n\t\td.logger.Error(\"failed to decode taskConfig state from handle\", \"error\", err, \"task_id\", handle.Config.ID)\n\t\treturn fmt.Errorf(\"failed to decode taskConfig state from handle: %v\", err)\n\t}\n\n\tplugRC, err := pstructs.ReattachConfigToGoPlugin(taskState.ReattachConfig)\n\tif err != nil {\n\t\td.logger.Error(\"failed to build ReattachConfig from taskConfig state\", \"error\", err, \"task_id\", handle.Config.ID)\n\t\treturn fmt.Errorf(\"failed to build ReattachConfig from taskConfig state: %v\", err)\n\t}\n\n\texecImpl, pluginClient, err := executor.ReattachToExecutor(\n\t\tplugRC,\n\t\td.logger.With(\"task_name\", handle.Config.Name, \"alloc_id\", handle.Config.AllocID),\n\t\td.nomadConfig.Topology.Compute(),\n\t)\n\n\tif err != nil {\n\t\td.logger.Error(\"failed to reattach to executor\", \"error\", err, \"task_id\", handle.Config.ID)\n\t\treturn fmt.Errorf(\"failed to reattach to executor: %v\", err)\n\t}","sourceCodeStart":377,"sourceCodeEnd":413,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/drivers/java/driver.go#L377-L413","documentation":"This error is returned by RecoverTask when handle.GetDriverState(&taskState) fails to decode the driver state that was previously stored in the task handle. The state contains the executor's reattach config and PID; without it the driver cannot reattach to the running task. Usually indicates corrupted, truncated, or version-incompatible state data.","triggerScenarios":"Nomad client restart recovery where the blob in the client state store cannot be gob/JSON-decoded into TaskState, e.g. after a Nomad version upgrade changed the struct, or the state file is corrupted/truncated.","commonSituations":"Upgrading Nomad across incompatible versions with running Java tasks; disk corruption or partial writes to the client data dir; state written by a different Nomad build.","solutions":["Restore the client state from a good backup or let the task be stopped/restarted (nomad stop/alloc stop) to clear the bad state","Check Nomad upgrade notes; the task state may not be portable across versions - restart the affected allocations","Inspect/repair the client's data_dir state files","If reproducible across upgrades, report the incompatible TaskState change to Nomad maintainers"],"exampleFix":"// remediation: restart the affected allocation to rebuild clean state\n// nomad alloc stop <alloc_id>","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := driver.RecoverTask(handle); err != nil {\n    if strings.Contains(err.Error(), \"failed to decode taskConfig state from handle\") {\n        // state is unrecoverable: stop and restart the allocation\n        _ = client.Allocations().Stop(ctx, alloc, nil)\n    }\n}","preventionTips":["Avoid restoring state across incompatible Nomad versions; follow upgrade runbooks","Back up data_dir and validate it after upgrades","Monitor client logs during recovery and alert on decode failures","Drain and restart allocations whose state fails to decode"],"tags":["nomad","java-driver","recover-task","state-corruption"],"backgroundTag":"driver-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"}