Troubleshooting

Practical fixes for the most common issues. If your problem is not listed here, open an issue on GitHub.

Connection test fails

Symptoms: The connection test in the Add/Edit account dialog returns an error, or no buckets load after saving.

Check these in order:

1. Credentials — verify the Access Key ID and Secret Access Key are copied correctly (no leading/trailing whitespace).
2. Region — the region must match where the bucket was created. For Amazon S3 use the AWS region identifier (e.g. us-east-1, eu-central-1). For Hetzner use the location code (e.g. fsn1, nbg1, hel1).
3. Endpoint — for custom S3-compatible providers the endpoint URL must include the scheme (https://) and no trailing slash. Hetzner endpoints are derived automatically from the region; you do not supply one.
4. Path-style addressing — providers such as Hetzner and most self-hosted S3-compatible services (MinIO, Garage) require path-style addressing. Enable Path-style addressing in the account form. Amazon S3 uses virtual-hosted style by default.

No buckets shown / region mismatch

If the connection test passes but the bucket list is empty, the credentials may lack s3:ListAllMyBuckets permission, or all your buckets are in a different region than the account’s configured region. S3 Manager lists buckets from the account’s configured region; buckets created in other regions will not appear unless you add separate accounts for those regions.

Uploads from a web page are blocked

Symptom: A browser upload using a presigned upload URL fails with a CORS error.

Browsers enforce CORS on cross-origin requests. The bucket must have a CORS rule that allows PUT from the page’s origin. Use the CORS Editor (CORS Editor) to add or update the bucket’s CORS configuration.

A minimal rule for browser uploads:

[
  {
    "AllowedOrigins": ["https://your-site.example.com"],
    "AllowedMethods": ["PUT"],
    "AllowedHeaders": ["*"]
  }
]

Presigned link expired or invalid

Symptom: A presigned GET or PUT URL returns 403 Access Denied or Request has expired.

Presigned URLs embed an expiry timestamp. Once that time passes, the URL is invalid. Check and adjust the default expiry in Presigned Links settings. For PUT upload links the expiry is set when the link is generated; generate a new one if needed.

Other causes: the credentials used to generate the link were revoked, or the system clock of the signing machine was significantly wrong at generation time.

Cannot shorten or remove a retention period

Symptom: Attempting to reduce or clear an object’s retention date returns an access denied or invalid request error.

Object Lock has two modes:

Mode	Can shorten retention?	Can remove retention?
Governance	Yes, with the s3:BypassGovernanceRetention permission	Yes, with the bypass permission
Compliance	No — never, not even by the bucket owner	No

If the bucket or object is in Compliance mode, the retention date cannot be shortened or removed by any user, including the account owner. This is by design and enforced by the provider.

See Object Lock for full details on retention modes.

Sync did not delete extra files at the destination

Symptom: After a sync run, the destination contains objects that do not exist in the source.

Sync in S3 Manager is additive and one-way: it copies new and updated files from source to destination but does not delete files at the destination that are absent from the source. This is intentional to prevent accidental data loss.

If you need to mirror a source exactly, manually delete the extra objects at the destination before or after syncing. See Sync for a full description of sync behavior.

macOS: “app can’t be opened” / Gatekeeper warning

Symptom: macOS displays a dialog saying the app cannot be opened because it is from an unidentified developer, or it is damaged.

Builds downloaded from GitHub Releases may show this warning if they are not notarized. Follow the steps in Installation to bypass Gatekeeper for a locally unsigned build (typically: right-click the app → Open → Open).

Windows: SmartScreen warning

Symptom: Windows Defender SmartScreen shows a blue warning before the installer runs.

This appears for executables that have not yet accumulated enough download reputation. Click More info → Run anyway to proceed. The installer is the official Squirrel-based setup produced by Electron Forge.