hashicorp/nomad · error

failed to read local task runner state: %v

Error message

failed to read local task runner state: %v

What it means

In the task-restore path of BoltStateDB, taskBkt.Get(taskLocalStateKey, ls) fails with an error other than not-found while restoring a task runner's LocalState, so GetTaskRunnerState aborts the whole restore transaction with this wrapped error.

Source

Thrown at client/state/db_bolt.go:664

		}

		allocBkt := allAllocsBkt.Bucket([]byte(allocID))
		if allocBkt == nil {
			// No state for alloc, return
			return nil
		}

		taskBkt := allocBkt.Bucket(taskBucketName(taskName))
		if taskBkt == nil {
			// No state for task, return
			return nil
		}

		// Restore Local State if it exists
		ls = &trstate.LocalState{}
		if err := taskBkt.Get(taskLocalStateKey, ls); err != nil {
			if !boltdd.IsErrNotFound(err) {
				return fmt.Errorf("failed to read local task runner state: %v", err)
			}

			// Key not found, reset ls to nil
			ls = nil
		}

		// Restore Task State if it exists
		ts = &structs.TaskState{}
		if err := taskBkt.Get(taskStateKey, ts); err != nil {
			if !boltdd.IsErrNotFound(err) {
				return fmt.Errorf("failed to read task state: %v", err)
			}

			// Key not found, reset ts to nil
			ts = nil
		}

		return nil

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Inspect the Bolt DB bucket for the affected alloc/task
2. If state is unrecoverable, delete the alloc bucket or wipe client state dir and let the client re-adopt
3. Ensure Nomad version compatibility of the stored state format

When it happens

Trigger: Thrown at client/state/db_bolt.go:664 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/d26cee07b94e603f. Report an issue: GitHub.