Troubleshooting
For detailed request/response/signature diagnostics, enable debug mode with the --debug flag (or VGW_DEBUG=true):
--debug enable debug output (default: false) [$VGW_DEBUG]
When enabled, each request will produce verbose output including:
- Incoming request headers and URL
- AWS Signature V4 canonical string and string-to-sign
- Response headers and body
This is intended for triaging authentication failures, signature mismatches, and unexpected client behavior. It should not be enabled in production due to the volume of output it generates.
[URL]: http://127.0.0.1:7070/
┌─────────────────────────────────────────────────[ REQUEST HEADERS ]──────────────────────────────────────────────────┐
│ Host : 127.0.0.1:7070 │
│ User-Agent : aws-cli/2.32.6 ... │
│ X-Amz-Date : 20260303T214033Z │
│ X-Amz-Content-Sha256 : e3b0c44298fc1c149afbf4c8996fb924... │
│ Authorization : AWS4-HMAC-SHA256 Credential=test/20260303/us-east-1/s3/aws4_request, ... │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
SDK 2026/03/03 13:40:33 DEBUG Request Signature:
---[ CANONICAL STRING ]-----------------------------
GET
/
host:127.0.0.1:7070
x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date:20260303T214033Z
host;x-amz-content-sha256;x-amz-date
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
---[ STRING TO SIGN ]--------------------------------
AWS4-HMAC-SHA256
20260303T214033Z
20260303/us-east-1/s3/aws4_request
515b5353210d091e085a5dfe79a66e03b4ce84acdd7c6ed5a420a60f08f979b6
-----------------------------------------------------
┌─────────────────────────────────────────────────[ RESPONSE HEADERS ]─────────────────────────────────────────────────┐
│ Content-Length : 459 │
│ Content-Type : application/xml │
│ Server : VERSITYGW │
│ Access-Control-Allow-Origin : * │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
───────────────────────────────────────────────────[ RESPONSE BODY ]────────────────────────────────────────────────────
<?xml version="1.0" encoding="UTF-8"?>
<ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">...</ListAllMyBucketsResult>
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
13:40:33 | vgw | 200 | 4.868708ms | 127.0.0.1 | GET | / | - |
The canonical string and string-to-sign are especially useful for diagnosing SignatureDoesNotMatch errors — compare these values against what your S3 client is computing to identify discrepancies in credentials, region, or clock skew.
See Debugging for additional debug and profiling options.
Most startup issues will print an associated error message to stdout. Common causes include:
-
Invalid credentials: ensure
--accessand--secret(or their environment variable equivalents) are set correctly. -
Port already in use: another process may be listening on the configured port. Use
--portto change the listen address. - Backend path not accessible: for POSIX backends, verify the root directory exists and the process has read/write permissions.
-
TLS misconfiguration: if
--certor--keyare provided, both must be valid PEM-encoded files and both must be specified together.
This error means the request signature computed by the client does not match what the gateway computed. Common causes:
-
Wrong access key or secret key — verify the credentials configured in the S3 client match the
--accessand--secretvalues used to start the gateway. - Clock skew — AWS Signature V4 requires the client and server clocks to be within 15 minutes of each other. Ensure both systems are synchronized (e.g. via NTP).
-
Wrong region — the region configured in the S3 client must match the
--regionoption used to start the gateway (default:us-east-1). - Wrong endpoint URL — path style vs. virtual host style addressing must match the client configuration. See VHost for virtual hosting setup.
Enable --debug to view the canonical string and string-to-sign on both sides and compare them to isolate the mismatch.
The access key in the request was not recognized. Check that the client is using the correct access key and that it matches the --access value (for the root user) or a configured IAM user account.
Ad blockers (such as uBlock Origin) can interfere with WebUI login requests, causing failures that appear in the browser console as CORS errors. See #1874.
Disable the ad blocker for the WebUI origin, or add an exception rule, to resolve this.
See S3 Client Configuration for detailed guidance on configuring specific S3 clients to work with versitygw.
-
Path style addressing: most clients default to virtual host style. versitygw uses path style by default. Configure the client to use path style requests, or enable virtual host style with
--virtual-domain. - TLS certificate errors: if using a self-signed certificate, configure the client to trust it or disable TLS verification (for testing only). See TLS.
- HTTP vs HTTPS: ensure the client endpoint scheme matches whether TLS is enabled on the gateway.
