Allocations bucket doesn't exist and transaction is not writ

Error message

Allocations bucket doesn't exist and transaction is not writable

What it means

Thrown by getAllocationBucket when the top-level 'allocations' bucket is absent and the bolt transaction is read-only (not writable). Since buckets can only be created in writable transactions, getAllocationBucket refuses to proceed rather than silently returning a nil bucket. This prevents callers from mistaking a missing DB for an empty one.

Source

Thrown at client/state/db_bolt.go:785

// Close releases all database resources and unlocks the database file on disk.
// All transactions must be closed before closing the database.
func (s *BoltStateDB) Close() error {
	return s.db.Close()
}

// getAllocationBucket returns the bucket used to persist state about a
// particular allocation. If the root allocation bucket or the specific
// allocation bucket doesn't exist, it will be created as long as the
// transaction is writable.
func getAllocationBucket(tx *boltdd.Tx, allocID string) (*boltdd.Bucket, error) {
	var err error
	w := tx.Writable()

	// Retrieve the root allocations bucket
	allocations := tx.Bucket(allocationsBucketName)
	if allocations == nil {
		if !w {
			return nil, fmt.Errorf("Allocations bucket doesn't exist and transaction is not writable")
		}

		allocations, err = tx.CreateBucketIfNotExists(allocationsBucketName)
		if err != nil {
			return nil, err
		}
	}

	// Retrieve the specific allocations bucket
	key := []byte(allocID)
	alloc := allocations.Bucket(key)
	if alloc == nil {
		if !w {
			return nil, fmt.Errorf("Allocation bucket doesn't exist and transaction is not writable")
		}

		alloc, err = allocations.CreateBucket(key)
		if err != nil {

View on GitHub (pinned to 482b49bf1a)

Solutions

Use db.Update (writable transaction) if you intend to create/initialize the allocations bucket
Run the client so upgrade migrations execute, which create the root bucket on a writable tx
If the DB is empty by design, tolerate this error and treat as 'no allocation state' in the caller
Verify you are opening the correct Nomad client state bolt file

Example fix

// before
var alloc *structs.Allocation
err := db.View(func(tx *boltdd.Tx) error {
    a, err := db.GetAllocation(tx, allocID)
    if err != nil {
        return err
    }
    alloc = a
    return nil
})
// after: fall back to writable tx on read-only bucket error
var alloc *structs.Allocation
err := db.View(func(tx *boltdd.Tx) error {
    a, err := db.GetAllocation(tx, allocID)
    if err != nil {
        return err
    }
    alloc = a
    return nil
})
if err != nil && strings.Contains(err.Error(), "transaction is not writable") {
    err = db.Update(func(tx *boltdd.Tx) error {
        a, err := db.GetAllocation(tx, allocID)
        if err != nil {
            return err
        }
        alloc = a
        return nil
    })
}

Defensive patterns

Strategy: fallback

Validate before calling

// pre-flight: ensure the state DB has been initialized at least once
ok, err := boltHasBucket(stateDBPath, "allocations")
if err != nil || !ok {
    // open in Update mode once to initialize buckets
}

Try / catch

err := db.View(func(tx *boltdd.Tx) error {
    alloc, err = db.GetAllocation(tx, allocID)
    return err
})
if err != nil && strings.Contains(err.Error(), "Allocations bucket doesn't exist") {
    // treat as empty state: initialize via Update or return nil
    alloc = nil
    err = nil
}

Prevention

Initialize the state DB once with a writable transaction at startup
Don't read from freshly created/empty state DBs with View
Keep the client's upgrade path intact so root buckets are created
Confirm the opened bolt file is the real Nomad state file

When it happens

Trigger: Calling GetAllocation (or any read path) via db.View() on a state DB that has no allocations bucket yet — e.g. a fresh/empty or wiped bolt file — or after a failed migration left the root bucket uncreated.

Common situations: Reading allocation state from a newly created or truncated client state DB; point-in-time copies of the state dir before any allocation ran; opening a state DB from a very old Nomad version pending upgrade migrations.

Related errors

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