What causes "must not be null" in hashicorp/terraform?

Provide the integer attribute in the backend block, e.g. `retry_max = 2`.

must not be null

Error message

must not be null

What it means

Returned by backendbase.IntValue when, after converting the cty.Value to cty.Number, the value is null. IntValue is the helper used by backends (e.g. http backend's retry_max, retry_wait_min/max at backend/remote-state/http/backend.go:187/198/209) to read integer attributes from the backend configuration block.

Source

Thrown at internal/backend/backendbase/helper.go:106

// Unless the fallback value is null itself, this function guarantees to never
// return null.
func GetAttrEnvDefaultFallback(v cty.Value, attrName string, defEnv string, fallback cty.Value) cty.Value {
	ret := GetAttrEnvDefault(v, attrName, defEnv)
	if ret.IsNull() {
		return fallback
	}
	return ret
}

// IntValue converts a cty value into a Go int64, or returns an error if that's
// not possible.
func IntValue(v cty.Value) (int64, error) {
	v, err := convert.Convert(v, cty.Number)
	if err != nil {
		return 0, err
	}
	if v.IsNull() {
		return 0, fmt.Errorf("must not be null")
	}
	bf := v.AsBigFloat()
	ret, acc := bf.Int64()
	if acc != big.Exact {
		return 0, fmt.Errorf("must not be a whole number")
	}
	return ret, nil
}

// BoolValue converts a cty value Go bool, or returns an error if that's not
// possible.
func BoolValue(v cty.Value) (bool, error) {
	v, err := convert.Convert(v, cty.Bool)
	if err != nil {
		return false, err
	}
	if v.IsNull() {
		return false, fmt.Errorf("must not be null")

View on GitHub (pinned to c9def3e214)

Solutions

Provide the integer attribute in the backend block, e.g. `retry_max = 2`.
If the attribute is optional, ensure the backend applies a default cty.Number before calling IntValue, or use GetAttrEnvDefaultFallback.
Fall back to an environment variable via GetAttrEnvDefault when the attribute is absent.
Validate the backend config schema early and report a clear 'attribute X is required' message.

Example fix

// before
terraform {
  backend "http" {
    address = "https://state.example.com"
    # retry_max omitted -> null -> 'must not be null'
  }
}
// after
terraform {
  backend "http" {
    address   = "https://state.example.com"
    retry_max = 2
  }
}

Defensive patterns

Strategy: validation

Validate before calling

v := getAttrOrNull(config, "retry_max")
if v.IsNull() {
    return errors.New("retry_max must not be null")
}
n, err := backendbase.IntValue(v)

Type guard

func isIntNullError(err error) bool {
    return err != nil && err.Error() == "must not be null"
}

Try / catch

n, err := backendbase.IntValue(v)
if err != nil {
    return fmt.Errorf("backend config: %w", err)
}

Prevention

Provide all required integer backend attributes.
Apply cty.Number defaults in the backend schema before IntValue.
Document required int fields clearly.

When it happens

Trigger: Returned at internal/backend/backendbase/helper.go:106 when v.IsNull() is true after convert.Convert(v, cty.Number). Triggered by any backend config schema using IntValue for a required integer attribute that the user left unset/null.

Common situations: Declaring a backend block but omitting a required integer field (e.g. `retry_max` for the http backend). Setting the attribute to null explicitly. A backend config that conditionally omits the field.

Related errors

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