> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudhumans.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fixes for the errors you'll actually hit: AccessDenied, InvalidObjectState, expired SSO tokens, and more.

## `AccessDenied` (403) on the first `aws s3 ls`

In this order, which is the real order of probability:

1. **Your identity-based policy is missing.** The most common cause, by far. Our bucket
   policy alone isn't enough for cross-account access. See
   [what you need to configure on your side](/data-export/overview#what-you-need-to-configure-on-your-side).
2. **The principal in use isn't the one you told us.** Confirm with
   `aws sts get-caller-identity --profile cloudhumans-export` and compare it against the
   ARN you sent. Assuming a role changes the effective ARN — what matters is what shows
   up here.
3. **Your organization's SCP is blocking cross-account S3**, or a VPC endpoint policy is
   restricting the bucket. Common in corporate environments with a landing zone.
4. **Wrong bucket name.** See the next entry.

## `AccessDenied` (403) where you expected `404`

You're missing `s3:ListBucket` in your policy. Without that permission, S3 returns 403
instead of 404 for a nonexistent object, deliberately — so it doesn't reveal whether the
key exists. A wrong key and a missing permission look identical. Add `s3:ListBucket` and
the error becomes honest.

## `ls` works but the download gives `AccessDenied`

You're missing `s3:GetObject`. `s3:ListBucket` applies to the bucket ARN;
`s3:GetObject` applies to the `bucket/*` ARN. Check that your policy has **both**
resources.

## `InvalidObjectState` on download

```text theme={null}
An error occurred (InvalidObjectState) when calling the GetObject operation:
The operation is not valid for the object's storage class
```

With `aws s3 cp`/`sync`, the same situation looks like this:

```text theme={null}
warning: Skipping file s3://<YOUR_BUCKET>/... . Object is of storage class GLACIER.
Unable to perform download operations on GLACIER objects. You must restore the object
to be able to perform the operation.
```

The object is 180 days old or more and archived. This isn't a permissions problem, and
it isn't the network. See
[restoring archived data](/data-export/storage-classes#restoring-archived-data).

## `aws s3 sync` exits with code 2 and Glacier warnings

Expected behavior when the prefix mixes hot and archived files: the CLI downloads what
it can and skips the rest. Two ways out:

* `--ignore-glacier-warnings` to proceed with what's available and exit with code 0.
* Restore what's missing and run again with `--force-glacier-transfer`.

## Restored the file, but `sync` still skips it

Expected, and not a bug on your end. Without `--force-glacier-transfer`, `sync` ignores
objects in Glacier even once restored — and in this case **without emitting a warning**,
because the listing it relies on has no way to know about the restore. Run it again with
the flag. See
[download after the restore](/data-export/storage-classes#download-after-the-restore) for
the detail and the measurement.

## `InvalidObjectState: Restore is not allowed for the object's current storage class`

The opposite of the previous case: you requested a restore for a file that **isn't**
archived. Only objects in `GLACIER` accept a restore. Filter by class first, as in
[restoring many files](/data-export/storage-classes#restoring-many-files).

## `NoSuchBucket` (404)

Wrong name, or the wrong region in your profile. The bucket lives in `us-east-1`.
Confirm with
`aws s3api get-bucket-location --bucket <YOUR_BUCKET> --profile cloudhumans-export`.

## `The specified sso-session does not exist`

The `[sso-session <session-name>]` block is missing from `~/.aws/config`, or its name
doesn't match the profile's `sso_session`. There are two blocks, and the name needs to
be identical in both. See [local profile](/data-export/overview#local-profile).

## `Error loading SSO Token: Token for <session-name> does not exist`

Configuration is correct, session isn't authenticated.
`aws sso login --profile cloudhumans-export`.

## `ExpiredToken` / `The security token included in the request is expired`

Your SSO session or temporary credential expired — usually in the middle of a 40 GB
sync, because the universe has a sense of humor. Run
`aws sso login --profile cloudhumans-export` and try again. `sync` is incremental, so it
resumes where it left off without re-downloading what already came through.

For long-running jobs in an orchestrator, prefer a role with a renewable session over a
terminal's temporary credential.

## `SlowDown` (503) or `RequestTimeout`

Concurrency is too high. Lower `max_concurrent_requests` and try again. S3 scales, but
it likes a ramp.

## Parquet file downloaded with the right size but unreadable

Check whether the partition had `_SUCCESS` at the time of the download. Without it, you
may have caught a partition mid-write. Download again once the marker appears.

## Support and contract changes

* **Layout and partition names** are stable within `v1/`. An incompatible change
  becomes `v2/`, with advance notice and a coexistence period between the two. You'll
  never wake up to a different `v1/`.
* **New tables** can appear inside `v1/` without notice. Write your pipeline to iterate
  over what exists, not over a fixed list.
* **Need help?** Contact your Cloud Humans account team. To speed things up, send along
  the exact command, the complete error message, and the output of
  `aws sts get-caller-identity`. With those three, most cases resolve on the first
  reply.