hashicorp/terraform · error

error describing table store %s: %#v

Error message

error describing table store %s: %#v

What it means

Returned by remoteClient() (backend_state.go:45-49) when both ots_endpoint and tablestore_table are configured and the TableStore DescribeTable call fails. The backend uses OTS for state locking and MD5 digests, so it sanity-checks the table on every workspace/client creation. The %#v dumps the underlying OTS SDK error verbatim.

Source

Thrown at internal/backend/remote-state/oss/backend_state.go:49

		return nil, errors.New("missing state name")
	}

	client := &RemoteClient{
		ossClient:            b.ossClient,
		bucketName:           b.bucketName,
		stateFile:            b.stateFile(name),
		lockFile:             b.lockFile(name),
		serverSideEncryption: b.serverSideEncryption,
		acl:                  b.acl,
		otsTable:             b.otsTable,
		otsClient:            b.otsClient,
	}
	if b.otsEndpoint != "" && b.otsTable != "" {
		_, err := b.otsClient.DescribeTable(&tablestore.DescribeTableRequest{
			TableName: b.otsTable,
		})
		if err != nil {
			return client, fmt.Errorf("error describing table store %s: %#v", b.otsTable, err)
		}
	}

	return client, nil
}

func (b *Backend) Workspaces() ([]string, tfdiags.Diagnostics) {
	var diags tfdiags.Diagnostics

	bucket, err := b.ossClient.Bucket(b.bucketName)
	if err != nil {
		return []string{""}, diags.Append(fmt.Errorf("error getting bucket: %#v", err))
	}

	var options []oss.Option
	options = append(options, oss.Prefix(b.statePrefix+"/"), oss.MaxKeys(1000))
	resp, err := bucket.ListObjects(options...)
	if err != nil {

View on GitHub (pinned to c9def3e214)

Solutions

1. In the OTS console, confirm a table named exactly tablestore_table exists under the ots_endpoint instance.
2. Verify ots_endpoint region matches the bucket region (e.g. both cn-hangzhou).
3. Grant the credentials/RAM role tablestore:DescribeTable and tablestore:GetRow/PutRow/DeleteRow on the table.
4. If you do not need locking, omit ots_endpoint and tablestore_table so the DescribeTable check is skipped.

Example fix

// before
backend "oss" {
  bucket = "tf-state"
  ots_endpoint = "https://tf-state.cn-hangzhou.ots.aliyuncs.com"
  tablestore_table = "terafom_lock"  // typo
}

// after
backend "oss" {
  bucket = "tf-state"
  ots_endpoint = "https://tf-state.cn-hangzhou.ots.aliyuncs.com"
  tablestore_table = "terraform_lock"
}

// Describe the OTS table yourself before running terraform, to fail fast.
func tableExists(c *tablestore.TableStoreClient, name string) error {
    _, err := c.DescribeTable(&tablestore.DescribeTableRequest{TableName: name})
    if err != nil {
        return fmt.Errorf("table %s not describable: %w", name, err)
    }
    return nil
}

// Catch during init; the error is returned from remoteClient. Re-run only after
// the table exists - retrying blindly won't help.
if err := tableExists(otsClient, otsTable); err != nil {
    return fmt.Errorf("pre-flight OTS check failed; create the table first: %w", err)
}

When it happens

Trigger: Calling remoteClient (via StateMgr, Workspaces, DeleteWorkspace) with an ots_table that does not exist on the configured ots_endpoint, or where the caller's credentials lack tablestore:DescribeTable permission. The DescribeTableRequest at line 45 returns a non-nil error.

Common situations: tablestore_table typo; table created in a different region/instance than ots_endpoint; OTS instance not yet provisioned; RAM policy missing ReadTableRow/DescribeTable; pointing ots_endpoint at the wrong OTS instance URL.

Related errors

• failed to lock OSS state: %s
• Error unlocking Alibaba Cloud OSS state file: Lock ID: %s E
• invoking PutRow got an error: %#v
• getting lock info got an error: %#v
• failed to retrieve lock info: %s

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