Skip to content

S3 remote pods: add troubleshooting section #1790

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jun 13, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions content/en/user-guide/state-management/cloud-pods/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -437,6 +437,30 @@ Full S3 remotes support is available in the CLI from version 3.2.0.
If you experience any difficulties, update your [LocalStack CLI]({{< ref "/getting-started/installation/#updating" >}}).
{{< /callout >}}

#### Troubleshooting

You might encounter an error like the following:

{{< command >}}
An error occurred (InvalidAccessKeyId) when calling the CreateBucket operation: The AWS Access Key Id you provided does not exist in our records.
{{< / command >}}

This means that you are likely using temporary AWS credentials and the S3 remote configuration is missing the `AWS_SESSION_TOKEN` environment variable.
To fix the issue, first export `AWS_SESSION_TOKEN` into your environment.
Then, be sure to add the `session_token` placeholder to the URL of the `pod remote add` command:

{{< command >}}
$ localstack pod remote add s3-storage-aws 's3://ls-pods-bucket-test/?access_key_id={access_key_id}&secret_access_key={secret_access_key}&session_token={session_token}'
{{< / command >}}

If you are experiencing issues connecting to the S3 bucket, you might need to add the S3 URL to the list of URLs that it resolved upstream, e.g.,:

```bash
DNS_NAME_PATTERNS_TO_RESOLVE_UPSTREAM=ls-pods-bucket-test.s3.amazonaws.com/
```

For more info, browse the [Skip LocalStack DNS Resolution]({{< ref "/user-guide/tools/dns-server/#skip-localstack-dns-resolution" >}}) section of our docs.

### ORAS remote storage

The ORAS remote enables users to store Cloud Pods in OCI-compatible registries like Docker Hub, Nexus, or ECS registries.
Expand Down