hashicorp/terraform · error

ErrStateVersionUnauthorizedUpgradeState

ErrStateVersionUnauthorizedUpgradeState

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

Returned at state.go:594 when the cloud state manager tries to read output values but falls back to reading the full state (because the state version lacks DetailedType, indicating it was created by terraform < 1.3.0), and the refreshed state is nil. A nil state at this point means the user lacks authorization to read the full state version. Terraform 1.3.0+ stores output type information so full-state reads are unnecessary, hence the upgrade advice.

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 d32a084675)

Solutions

1. Upgrade the workspace's terraform version to 1.3.0 or newer and run a successful apply to regenerate state with detailed output types.
2. Grant the API token or user 'Read' access to full state versions in the TFC/TFE workspace permissions.
3. Run 'terraform refresh' or 'terraform apply' with a newer terraform binary to upgrade the state format.
4. If using a service account, ensure its team has the appropriate state access level.

Example fix

// before: state created with terraform < 1.3.0, token lacks full-state read
// error: You are not authorized to read the full state version...

// after: upgrade terraform and apply to regenerate state
terraform version  # ensure >= 1.3.0
terraform apply    # regenerates state with detailed output types
// OR grant 'State Version Access: Read' in TFC workspace settings

// Before reading outputs, check terraform version compatibility:
// if terraformVersion < 1.3.0 {
//     log.Warn("upgrade to terraform >= 1.3.0 to avoid full-state read requirements")
// }
// Ensure the API token has 'State Version Access: Read' permission

// if errors.Is(err, cloud.ErrStateVersionUnauthorizedUpgradeState) {
//     return fmt.Errorf("upgrade terraform to >= 1.3.0 or grant state read access: %w", err)
// }

When it happens

Trigger: A cloud-backed workspace has state created by terraform < 1.3.0 (no DetailedType on outputs). The code at state.go:578-583 detects missing DetailedType, calls RefreshState() to read the full state, but state.go:590 finds state == nil because the API token/user lacks 'read full state' permissions. Returns ErrStateVersionUnauthorizedUpgradeState.

Common situations: A workspace that has been running terraform since before v1.3.0 and was never upgraded; a service account or team with limited permissions (no 'State Version Access: Read' for full state); migrating a legacy workspace to TFC without upgrading the state format.

Related errors

• Error retrieving state: %v
• error reading output values: %s
• error converting output values to json: %s
• could not read state version outputs: %w
• could not read state version output %s: %w

AI-assisted analysis of hashicorp/terraform@d32a084675 (2026-08-11). Data as JSON: /api/errors/ea9777d6c9876fba. Report an issue: GitHub.