Troubleshoot errors and inspect logs
Start with the message from the action that failed. Permission denials, disabled capabilities and network errors require different fixes. If the action involves several items, check their suboperations and any available report: some changes may have succeeded before the error.
Check the connection and credentials
- Open File > Accounts….
- Select the affected account and click Edit….
- Click Test connection.
- Click Details… to open Connection test and read the result and error details. Check the relevant fields or credential source before trying again.
The test loads credentials and makes an S3 request. It does not check every permission required for transfers or properties.
| Symptom or code | Cause and action |
|---|---|
| AccessDenied in the test | The service denied the request to list buckets or read the contents of the first configured bucket. Check the denial details and permissions; for an account without bucket-listing permission, also check its configured bucket list. |
| InvalidAccessKeyId | The service does not recognize the access key. Check the account, target service, and key. |
| SignatureDoesNotMatch | The signature was rejected. Check the secret key, endpoint, Region, and signature version. |
| RequestExpired | The request has expired. Check your computer’s clock and rerun the test. |
| ExpiredToken or TokenRefreshRequired | Temporary credentials or the session token have expired. Renew them at their source; for SSO, check your sign-in session. |
| Credentials could not be loaded: … | The credential source did not provide usable credentials. Check the specified profile, external process, SSO session, or metadata service. |
| Connection failed., with details identifying a proxy error | The proxy or proxy authentication blocked the request. Check Tools > Options… > Network. |
| Connection failed., with details identifying a network error | The request failed at the network layer. Check the host, port, DNS resolution, connection, and the TLS or network error details. |
See connections, credential sources, and proxy configuration for the corresponding procedures. An S3 denial during another action requires checking that action’s permissions; a successful connection test does not guarantee them.
Understand unavailable commands and denials
Check the active pane, selection, and item type: some commands require one object, a folder, or a bucket. Delete markers have no content to copy or preview. Historical versions do not necessarily support the same changes as current objects.
If the command depends on an account capability, open File > Accounts…, select the account, then click Edit…, then open Capabilities. Check the relevant capability and policy using the configuration guide. The service must support the feature and your credentials must have the required permissions.
Some settings also depend on bucket state, including versioning, Object Lock, and object ownership. If a tab reports a denied or failed read, fix the cause and reload its data before editing.
During a copy, respond to the overwrite or folder merge confirmation dialog that opens automatically. Synchronization has no per-file decision dialog: a detected conflict appears in its result and requires checking the locations before preparing another synchronization. Check the source and destination before rerunning a partially completed action. See operation monitoring and synchronization.
Understand ACL-related denials
Read the error code and the full message. The settings are under File > Accounts… > Edit… > Capabilities > ACL policy.
| Symptom | Cause and action |
|---|---|
AclDisabled | The message distinguishes ACL operations disabled in the account from ACLs disabled by the bucket. An explicit ACL is still rejected; choose the destination default if you do not require an ACL. |
AclPreservationImpossible | The operation requires ACL preservation but cannot guarantee it. Check the accounts, bucket and required capabilities. Disabling ACL operations does not satisfy this requirement. |
AclWritePathUnavailable | No configured write method can carry the requested ACL through the selected transfer. Check the request forms the service actually supports. With ACL operations disabled in the destination account, an ordinary transfer using the destination default needs no ACL write method. |
AccessDenied | The credentials do not permit the request. Check policies and permissions; this denial does not prove that ACLs are disabled or unsupported. |
After changing the account, reopen the dialog and prepare a new operation: an operation already prepared retains its captured configuration. See ACLs and ownership to distinguish the local choice, Bucket owner enforced and API limits.
Recognize partial results and refused previews
After an interruption or navigation error, the displayed list may be provisional or left over from the previous read. It cannot confirm the full current contents. The Navigation error dialog reports the cause of a failed read or refresh. Resolve it and refresh again, as explained in the pane guide.
After a copy, deletion, or bulk change, check child operations and failed items, along with any available summary, then refresh the affected location. Aborting an operation preserves changes already made; it does not automatically restore the original state.
A refused preview may result from the format, a size limit, decoding, a missing SSE-C key, or an archived object that has not been restored. Depending on the message, check previews, preview settings, encryption, or archives. A partial text preview may simply have reached the configured content limit.
Enable HTTP/HTTPS traces
Logging is disabled by default. Enable it before reproducing the action; it cannot reconstruct earlier exchanges. Logging adds processing and in-memory content, especially for large XML responses.
- Open Tools > Options… > HTTP Logging.
- Select Enable HTTP logging to record exchange traces for S3 operations.
- Select Add request bodies (xml elements) and Add response bodies (xml elements) if XML bodies are useful. Both are checked by default, but are active only when logging is enabled. They do not capture the contents of transferred files.
- Add signing details (‘canonical request’ and ‘string to sign’) adds signing details. It is unchecked by default, available in release builds as well, and can be enabled only when logging is enabled.
- Click OK, then reproduce the action.
Recognized sensitive values in headers, signing parameters, and XML elements are replaced with [redacted], including authorization, tokens, and SSE-C keys. Logs may still contain bucket names, object keys, endpoints, and metadata: review them before sharing.
Inspect and export details
- Wait for the operation to finish or be aborted, then select a single row in the operations list below the panes. Expand its tree if you want to inspect a child operation.
- Choose Show details from the context menu or use the corresponding button. The command is available when the finished or aborted row has a log, error or result summary to inspect.
- In Operation details, read the details and the summary, if present. Font and Size change only the text presentation.
- Click Save….
- Choose a name and location for the text file and save it. The details text is exported as UTF-8; copy the summary above it separately if needed for the report.
Show error message displays the selected row’s error, when present. Save details before removing an operation or closing S3Client; session logs are not retained as a history.
To report a problem, email and include the S3Client version, platform, S3 service, action and selection, expected result, exact message or code, and steps to reproduce the problem. Attach relevant details after reviewing them, without secret keys, tokens, or SSE-C keys.
After troubleshooting, return to HTTP Logging, clear Enable HTTP logging, and click OK.