hashicorp/terraform · error

failed to generate initial lineage: %v

Error message

failed to generate initial lineage: %v

What it means

Returned by the state persister when, on a fresh workspace (s.readState == nil and lineage == ""), uuid.GenerateUUID() fails to produce a new state lineage UUID. UUID generation in this codebase is cryptographic random, so failure is exceptionally rare.

Source

Thrown at internal/cloud/state.go:194

			// If the state, lineage or serial haven't changed at all then we have nothing to do.
			return nil
		}
		s.serial++
	} else {
		// We might be writing a new state altogether, but before we do that
		// we'll check to make sure there isn't already a snapshot present
		// that we ought to be updating.
		err := s.refreshState()
		if err != nil {
			return fmt.Errorf("failed checking for existing remote state: %s", err)
		}
		log.Printf("[DEBUG] cloud/state: after refresh, state read serial is: %d; serial is: %d", s.readSerial, s.serial)
		log.Printf("[DEBUG] cloud/state: after refresh, state read lineage is: %s; lineage is: %s", s.readLineage, s.lineage)

		if s.lineage == "" { // indicates that no state snapshot is present yet
			lineage, err := uuid.GenerateUUID()
			if err != nil {
				return fmt.Errorf("failed to generate initial lineage: %v", err)
			}
			s.lineage = lineage
			s.serial++
		}
	}

	f := statefile.New(s.state, s.lineage, s.serial)

	var buf bytes.Buffer
	err := statefile.Write(f, &buf)
	if err != nil {
		return err
	}

	var jsonState []byte
	if schemas != nil {
		jsonState, err = jsonstate.Marshal(f, schemas)
		if err != nil {

View on GitHub (pinned to c9def3e214)

Solutions

1. Retry the operation (transient entropy issues usually clear).
2. Verify /dev/urandom (or the platform CSPRNG) is available and readable in the execution environment.
3. If reproducible, inspect the host's RNG health and container device mappings.

Example fix

// before: first apply on fresh workspace fails generating lineage
// after: ensure /dev/urandom is available in the container, then re-run
docker run --device /dev/urandom ... terraform apply

// Sanity-check the CSPRNG is available before first write.
if _, err := os.Open("/dev/urandom"); err != nil {
    return fmt.Errorf("no CSPRNG available for state lineage")
}

var lineage string
for i := 0; i < 3; i++ {
    var e error
    lineage, e = uuid.GenerateUUID()
    if e == nil { break }
    time.Sleep(100 * time.Millisecond)
}

When it happens

Trigger: First-ever state write to a cloud workspace; refreshState found no existing state so lineage is empty; the UUID generator's crypto/rand source returns an error (entropy exhaustion).

Common situations: Effectively never on normal systems. Could occur on a severely constrained environment where crypto/rand read fails (broken /dev/urandom, chroot/container without the device).

Related errors

• Failed to retrieve workspace %s: %v
• Remote workspace Terraform version %q does not match local T
• error loading state: %w
• failed checking for existing remote state: %s
• failed to read state: %w

AI-assisted analysis of hashicorp/terraform@c9def3e214 (2026-08-07). Data as JSON: /api/errors/4eb641f1bcca5171. Report an issue: GitHub.