%s%s: MinItems and MaxItems must be set to either 0 or 1 in

Error message

%s%s: MinItems and MaxItems must be set to either 0 or 1 in NestingSingle mode

What it means

In NestingSingle mode (and after 817 passed, i.e. Min==Max), the common value must be 0 or 1 (checked at lines 78-79). A single block can be optional (0/0) or required (1/1); anything else is nonsensical for single nesting. Values >1 imply you want multiple, which is NestingList territory.

Source

Thrown at internal/configs/configschema/internal_validate.go:79

			multiErr = errors.Join(multiErr, fmt.Errorf("%s%s: DeprecationMessage must not be set when Deprecated is false", prefix, name))
		}

		if blockS.MinItems < 0 || blockS.MaxItems < 0 {
			multiErr = errors.Join(multiErr, fmt.Errorf("%s%s: MinItems and MaxItems must both be greater than zero", prefix, name))
		}

		// any nested blocks within a computed block must also be computed
		if b.Computed && !blockS.Computed {
			multiErr = errors.Join(multiErr, fmt.Errorf("%s%s: all nested blocks within computed blocks must also be computed", prefix, name))
		}

		switch blockS.Nesting {
		case NestingSingle:
			switch {
			case blockS.MinItems != blockS.MaxItems:
				multiErr = errors.Join(multiErr, fmt.Errorf("%s%s: MinItems and MaxItems must match in NestingSingle mode", prefix, name))
			case blockS.MinItems < 0 || blockS.MinItems > 1:
				multiErr = errors.Join(multiErr, fmt.Errorf("%s%s: MinItems and MaxItems must be set to either 0 or 1 in NestingSingle mode", prefix, name))
			}
		case NestingGroup:
			if blockS.MinItems != 0 || blockS.MaxItems != 0 {
				multiErr = errors.Join(multiErr, fmt.Errorf("%s%s: MinItems and MaxItems cannot be used in NestingGroup mode", prefix, name))
			}
			if blockS.Computed {
				multiErr = errors.Join(multiErr, fmt.Errorf("%s%s: NestingGroup blocks cannot be computed", prefix, name))
			}
		case NestingList, NestingSet:
			if blockS.MinItems > blockS.MaxItems && blockS.MaxItems != 0 {
				multiErr = errors.Join(multiErr, fmt.Errorf("%s%s: MinItems must be less than or equal to MaxItems in %s mode", prefix, name, blockS.Nesting))
			}
			if blockS.Nesting == NestingSet {
				ety := blockS.Block.ImpliedType()
				if ety.HasDynamicTypes() {
					// This is not permitted because the HCL (cty) set implementation
					// needs to know the exact type of set elements in order to
					// properly hash them, and so can't support mixed types.

View on GitHub (pinned to c9def3e214)

Solutions

Use 0/0 (optional single) or 1/1 (required single).
For multiple required blocks, switch to NestingList with MinItems=2.

Example fix

// before
"replicas": {Nesting: configschema.NestingSingle, MinItems: 2, MaxItems: 2}

// after
"replicas": {Nesting: configschema.NestingList, MinItems: 2, MaxItems: 2}

Defensive patterns

Strategy: validation

Validate before calling

if nb.Nesting == configschema.NestingSingle && (nb.MinItems < 0 || nb.MinItems > 1) {
    return fmt.Errorf("NestingSingle MinItems/MaxItems must be 0 or 1")
}

Prevention

NestingSingle means at most one instance; use list/set nesting for counts > 1.
Remember 0/0 = optional single, 1/1 = required single.

When it happens

Trigger: Setting MinItems=MaxItems=2 (or any value >1) on a NestingSingle block, e.g. trying to require 'exactly 2' of a single block.

Common situations: Misusing NestingSingle as a list, generated schemas that emit a required-count onto a single block.

Related errors

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