hashicorp/terraform · error · ErrStateVersionUnauthorizedUpgradeState

You are not authorized to read the full state version contai

Error message

You are not authorized to read the full state version containing outputs.
State versions created by terraform v1.3.0 and newer do not require this level
of authorization and therefore this error can usually be fixed by upgrading the
remote state version.

What it means

ErrStateVersionUnauthorizedUpgradeState is returned by State.GetRootOutputValues when a state version output lacks DetailedType (meaning the state was written by Terraform <1.3.0), forcing a fallback to read the full state, but the caller is not authorized to read the full state and the state comes back nil. Because Terraform >=1.3.0 stores detailed output types that don't require full-state authorization, the message points the user at upgrading the remote state version.

Source

Thrown at internal/cloud/state.go:81

	workspace            *tfe.Workspace
	stateUploadErr       bool
	forcePush            bool
	lockInfo             *statemgr.LockInfo

	// The server can optionally return an X-Terraform-Snapshot-Interval header
	// in its response to the "Create State Version" operation, which specifies
	// a number of seconds the server would prefer us to wait before trying
	// to write a new snapshot. If this is non-zero then we'll wait at least
	// this long before allowing another intermediate snapshot. This does
	// not effect final snapshots after an operation, which will always
	// be written to the remote API.
	stateSnapshotInterval time.Duration
	// If the header X-Terraform-Snapshot-Interval is present then
	// we will enable snapshots
	enableIntermediateSnapshots bool
}

var ErrStateVersionUnauthorizedUpgradeState = errors.New(strings.TrimSpace(`
You are not authorized to read the full state version containing outputs.
State versions created by terraform v1.3.0 and newer do not require this level
of authorization and therefore this error can usually be fixed by upgrading the
remote state version.
`))

var _ statemgr.Full = (*State)(nil)
var _ statemgr.Migrator = (*State)(nil)
var _ statemgr.IntermediateStateConditionalPersister = (*State)(nil)

// statemgr.Reader impl.
func (s *State) State() *states.State {
	s.mu.Lock()
	defer s.mu.Unlock()

	return s.state.DeepCopy()
}

View on GitHub (pinned to c9def3e214)

Solutions

Run a 'terraform apply' with Terraform >=1.3.0 against the workspace so a new state version (with detailed output types) is written.
If you cannot apply, grant the API token/team the 'Read Full State' permission on the workspace.
Upgrade the Terraform CLI version locally to >=1.3.0 before reading outputs.

Example fix

# before: outputs read with <1.3.0 state + read-only token -> unauthorized
# after: write a new state version with >=1.3.0
$ terraform version          # ensure >= 1.3.0
$ terraform apply -auto-approve

Defensive patterns

Strategy: fallback

Validate before calling

// Detect the pre-1.3.0 state early and prompt an upgrade rather than failing on output read.
func ensureDetailedOutputs(client *tfe.Client, ws string) error {
    outs, err := client.StateVersionOutputs.ReadCurrent(ctx, ws)
    if err != nil { return err }
    for _, o := range outs.Items {
        if o.DetailedType == nil {
            return errors.New("state predates v1.3.0 outputs; run 'terraform apply' with TF >= 1.3.0 to upgrade the state version")
        }
    }
    return nil
}

Try / catch

// Fall back gracefully: if outputs can't be read, surface upgrade guidance.
outputs, err := state.GetRootOutputValues(ctx)
if errors.Is(err, cloud.ErrStateVersionUnauthorizedUpgradeState) {
    log.Println("upgrade the remote state version with Terraform >= 1.3.0, or grant read-full-state permission")
    return nil, errUpgradeRequired
}

Prevention

Keep Terraform CLI >= 1.3.0 so new state versions carry detailed output types.
Grant 'Read Full State' to service tokens that must read legacy state.
After upgrading Terraform, run an apply to write a new-format state version.

When it happens

Trigger: state.go:578-595: output.DetailedType == nil triggers the full-state fallback; s.RefreshState() is called, then s.State() is checked. If state is nil (unauthorized read or empty after refresh), ErrStateVersionUnauthorizedUpgradeState is returned. The token in use lacks 'read full state' permission.

Common situations: A workspace whose state was last written by Terraform <1.3.0; a read-only API token / team with limited permissions reading outputs; migrating an old workspace into HCP Terraform without re-running apply under a newer Terraform.

Related errors

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