hashicorp/terraform · error

Unable to access object %q in S3 bucket %q: %w

Error message

Unable to access object %q in S3 bucket %q: %w

What it means

Thrown in RemoteClient.get() (s3/client.go:146) when HeadObject fails with an error that is neither NoSuchBucket nor *s3types.NotFound. The wrapped (%w) error is the raw AWS SDK error, so its code is inspectable. This is the catch-all for any HEAD-object access problem on an existing bucket.

Source

Thrown at internal/backend/remote-state/s3/client.go:146

	headInput := &s3.HeadObjectInput{
		Bucket: aws.String(c.bucketName),
		Key:    aws.String(c.path),
	}
	if c.serverSideEncryption && c.customerEncryptionKey != nil {
		headInput.SSECustomerKey = aws.String(base64.StdEncoding.EncodeToString(c.customerEncryptionKey))
		headInput.SSECustomerAlgorithm = aws.String(s3EncryptionAlgorithm)
		headInput.SSECustomerKeyMD5 = aws.String(c.getSSECustomerKeyMD5())
	}

	headOut, err := c.s3Client.HeadObject(ctx, headInput)
	if err != nil {
		switch {
		case IsA[*s3types.NoSuchBucket](err):
			return nil, fmt.Errorf(errS3NoSuchBucket, c.bucketName, err)
		case IsA[*s3types.NotFound](err):
			return nil, nil
		}
		return nil, fmt.Errorf("Unable to access object %q in S3 bucket %q: %w", c.path, c.bucketName, err)
	}

	// Pre-allocate the full buffer to avoid re-allocations and GC
	buf := make([]byte, int(aws.ToInt64(headOut.ContentLength)))
	w := manager.NewWriteAtBuffer(buf)

	downloadInput := &s3.GetObjectInput{
		Bucket: aws.String(c.bucketName),
		Key:    aws.String(c.path),
	}
	if c.serverSideEncryption && c.customerEncryptionKey != nil {
		downloadInput.SSECustomerKey = aws.String(base64.StdEncoding.EncodeToString(c.customerEncryptionKey))
		downloadInput.SSECustomerAlgorithm = aws.String(s3EncryptionAlgorithm)
		downloadInput.SSECustomerKeyMD5 = aws.String(c.getSSECustomerKeyMD5())
	}

	downloader := manager.NewDownloader(c.s3Client)

View on GitHub (pinned to c9def3e214)

Solutions

1. Grant s3:GetObject on the state object (and kms:Decrypt on the KMS key if SSE-KMS is used).
2. If using SSE-C, supply the correct customer key in the backend config.
3. Retry on SlowDown/throttling with backoff.
4. Use object ownership controls / ACLs so the caller can read cross-account objects.

Example fix

// before: role lacks kms:Decrypt on the CMK

// after: attach a KMS grant/key policy allowing the role to decrypt
// {
//   "Effect": "Allow",
//   "Action": ["kms:Decrypt", "kms:DescribeKey"],
//   "Resource": "arn:aws:kms:us-west-2:111122223333:key/<key-id>"
// }

// Probe read access (and KMS) on the state object before the run
// _, err := s3Client.HeadObject(ctx, &s3.HeadObjectInput{Bucket:&bucket, Key:aws.String(stateKey)})
// if err != nil { /* fix s3:GetObject / kms:Decrypt / SSE-C key */ }

// Narrow the wrapped error to react by AWS error code
// var apiErr smithy.APIError
// if errors.As(err, &apiErr) {
//   switch apiErr.ErrorCode() {
//   case "AccessDenied":   /* IAM / KMS / SSE-C */
//   case "InvalidArgument":/* SSE-C key problem */
//   case "SlowDown":       /* retry */
//   }
// }

// Distinguish retryable throttling from hard permission errors
// var apiErr smithy.APIError
// if errors.As(err, &apiErr) && apiErr.ErrorCode()=="SlowDown" { /* backoff */ } else { return err }

When it happens

Trigger: s3:GetObject denied (AccessDenied); SSE-C customer key missing or wrong (InvalidArgument/403); KMS key denied (kms:Decrypt missing); S3 throttling (SlowDown); network error; object stored with a checksum algorithm the SDK rejects.

Common situations: Least-privilege role missing s3:GetObject; bucket encrypted with customer-provided keys but SSE-C key not configured; KMS-encrypted state with no kms:Decrypt grant; cross-account object owned by another account.

Related errors

• Unable to list objects in S3 bucket %q with prefix %q: %w
• failed to upload state: %w
• failed to unlock both S3 and DynamoDB: S3 error: %v, DynamoD
• failed to unlock S3: %v
• unable to retrieve file from S3 bucket '%s' with key '%s': %

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