hashicorp/nomad · error

failed to retrieve allocation bucket

Error message

failed to retrieve allocation bucket: %v

What it means

putTaskRunnerLocalStateImpl calls getTaskBucket to obtain/create the per-task bucket inside the alloc bucket; this error is returned when the bucket cannot be fetched or created, so persisting TaskRunner LocalState fails and the write transaction aborts.

Solutions

  1. Check that the alloc bucket exists (state not wiped mid-run)
  2. Inspect DB health/permissions on the client state dir
  3. Retry after transient bolt errors; recreate state via alloc re-adoption
Defensive patterns

Strategy: retry

When it happens

Trigger: Thrown at client/state/db_bolt.go:704 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/8f077019238a3796. Report an issue: GitHub.

Appendix: source

Thrown at client/state/db_bolt.go:704

		return nil, nil, err
	}

	return ls, ts, nil
}

// PutTaskRunnerLocalState stores TaskRunner's LocalState or returns an error.
func (s *BoltStateDB) PutTaskRunnerLocalState(allocID, taskName string, val *trstate.LocalState) error {
	return s.db.Update(func(tx *boltdd.Tx) error {
		return putTaskRunnerLocalStateImpl(tx, allocID, taskName, val)
	})
}

// putTaskRunnerLocalStateImpl stores TaskRunner's LocalState in an ongoing
// transaction or returns an error.
func putTaskRunnerLocalStateImpl(tx *boltdd.Tx, allocID, taskName string, val *trstate.LocalState) error {
	taskBkt, err := getTaskBucket(tx, allocID, taskName)
	if err != nil {
		return fmt.Errorf("failed to retrieve allocation bucket: %v", err)
	}

	if err := taskBkt.Put(taskLocalStateKey, val); err != nil {
		return fmt.Errorf("failed to write task_runner state: %v", err)
	}

	return nil
}

// PutTaskState stores a task's state or returns an error.
func (s *BoltStateDB) PutTaskState(allocID, taskName string, state *structs.TaskState) error {
	return s.db.Update(func(tx *boltdd.Tx) error {
		return putTaskStateImpl(tx, allocID, taskName, state)
	})
}

// putTaskStateImpl stores a task's state in an ongoing transaction or returns
// an error.

View on GitHub (pinned to 482b49bf1a)