hashicorp/terraform · error

must be eight hexadecimal digits

Error message

must be eight hexadecimal digits

What it means

Returned by ParseDeposedKey when the raw string's length is not exactly 8. A DeposedKey must be exactly eight lowercase hex characters (NewDeposedKey formats a uint32 as %08x). This first length check catches anything that isn't 8 chars before format validation.

Source

Thrown at internal/addrs/resource.go:620

// key.
const NotDeposed = DeposedKey("")

var deposedKeyRand = rand.New(rand.NewSource(time.Now().UnixNano()))

// NewDeposedKey generates a pseudo-random deposed key. Because of the short
// length of these keys, uniqueness is not a natural consequence and so the
// caller should test to see if the generated key is already in use and generate
// another if so, until a unique key is found.
func NewDeposedKey() DeposedKey {
	v := deposedKeyRand.Uint32()
	return DeposedKey(fmt.Sprintf("%08x", v))
}

// ParseDeposedKey parses a string that is expected to be a deposed key,
// returning an error if it doesn't conform to the expected syntax.
func ParseDeposedKey(raw string) (DeposedKey, error) {
	if len(raw) != 8 {
		return "00000000", fmt.Errorf("must be eight hexadecimal digits")
	}
	if raw != strings.ToLower(raw) {
		return "00000000", fmt.Errorf("must use lowercase hex digits")
	}
	_, err := hex.DecodeString(raw)
	if err != nil {
		return "00000000", fmt.Errorf("must be eight hexadecimal digits")
	}
	return DeposedKey(raw), nil
}

func (k DeposedKey) String() string {
	return string(k)
}

func (k DeposedKey) GoString() string {
	ks := string(k)
	switch {

View on GitHub (pinned to c9def3e214)

Solutions

1. Regenerate the deposed key with addrs.NewDeposedKey() (which always yields 8 lowercase hex chars) rather than constructing strings manually.
2. If the value comes from a proto/external source, validate len==8 before passing to ParseDeposedKey.
3. Inspect the offending state/plan to find which resource instance has the bad deposed key and repair it (e.g. `terraform state` operations or re-running the plan).
4. Round-trip state through a supported Terraform version to normalize keys.

if len(raw) != 8 {
    return fmt.Errorf("deposed key must be 8 chars, got %d", len(raw))
}

func isDeposedKeyParseError(err error) bool {
    return err != nil && strings.Contains(err.Error(), "eight hexadecimal digits") && strings.Contains(err.Error(), "must be")
}

k, err := addrs.ParseDeposedKey(raw)
if err != nil {
    // regenerate a valid key rather than propagate bad input
    k = addrs.NewDeposedKey()
}

When it happens

Trigger: Returned at internal/addrs/resource.go:620 when len(raw) != 8. ParseDeposedKey is called from stackplan/from_proto.go:458/495 (parsing deposed keys out of stack plan protos) and stackstate/statekeys/resources.go:38, plus the states.ParseDeposedKey alias.

Common situations: A stack plan/state proto carries a deposed key that is empty, truncated, or a full SHA-style string. State migration or hand-editing produced an invalid key. External tooling generated a deposed key without the %08x formatting. Corrupted or partial state import.

Related errors

• must use lowercase hex digits
• ErrInvalidSHA256Hash
• lock id %q does not match existing lock
• default state is not allowed to be deleted
• error reading state: %s

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