hashicorp/nomad · error

failed to fetch first index: %v

Error message

failed to fetch first index: %v

What it means

After successfully opening the BoltDB store, raftStateInfoBoltDB calls s.FirstIndex() to read the lowest persisted Raft log index. This error wraps a failure of that read — the store opened but its log index data is unreadable or the underlying Bolt transaction failed.

Source

Thrown at helper/raftutil/state.go:69

	opts := raftboltdb.Options{
		Path: p,
		BoltOptions: &bbolt.Options{
			ReadOnly: true,
			Timeout:  1 * time.Second,
		},
		MsgpackUseNewTimeFormat: true,
	}
	s, err := raftboltdb.New(opts)
	if err != nil {
		if strings.HasSuffix(err.Error(), "timeout") {
			return nil, 0, 0, errAlreadyOpen
		}
		return nil, 0, 0, fmt.Errorf("failed to open raft logs: %v", err)
	}

	firstIdx, err = s.FirstIndex()
	if err != nil {
		return nil, 0, 0, fmt.Errorf("failed to fetch first index: %v", err)
	}

	lastIdx, err = s.LastIndex()
	if err != nil {
		return nil, 0, 0, fmt.Errorf("failed to fetch last index: %v", err)
	}

	return s, firstIdx, lastIdx, nil
}

func raftStateInfoWAL(p string) (store RaftStore, firstIdx uint64, lastIdx uint64, err error) {
	s, err := raftwal.Open(p)
	if err != nil {
		return nil, 0, 0, fmt.Errorf("failed to open WAL logs: %v", err)
	}

	firstIdx, err = s.FirstIndex()
	if err != nil {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check the embedded error: BoltDB 'invalid database' or bucket errors mean corruption — restore from a verified snapshot.
2. Run against a consistent copy of raft.db taken while the agent was stopped.
3. Try consul's built-in recovery/verify tooling on the raft.db before manual inspection.
4. If only the logs bucket is damaged but a snapshot exists, rebuild state from the snapshot instead.

store, first, _, err := raftutil.RaftStateInfo(raftDB)
if err != nil {
    if strings.Contains(err.Error(), "failed to fetch first index") {
        log.Printf("log index unreadable (likely corruption): %v — restore from snapshot", err)
        return
    }
    defer store.Close()
}

When it happens

Trigger: s.FirstIndex() erroring on an opened raftboltdb store: BoltDB bucket ('logs') missing or corrupt, I/O error reading the meta/index pages, or database pages damaged such that index queries fail.

Common situations: raft.db from a crashed node with damaged meta/logs buckets, a raft.db truncated by disk-full conditions, or a file that opens as BoltDB but is not a Consul Raft store (different schema).

Related errors

• failed to open raft logs: %v
• failed to fetch last index: %v
• failed to open raft store %v: %v
• failed to read log entry at index %d: %v
• failed to open BoltDB store: %w

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