Troubleshooting

Signature Mismatch

Symptom

SDK calls fail with SignatureDoesNotMatch.

Likely Cause

The endpoint, region, key pair, or path-style setting does not match the storage deployment.

Fix

Use the same values in every application:

S3_ENDPOINT=https://storage.example.local
S3_REGION=us-east-1
S3_USE_PATH_STYLE_ENDPOINT=true

Regenerate credentials in Quat if you are unsure whether the secret key is current.

Endpoint Connection Errors

Symptom

SDK calls fail with connection refused, DNS errors, or TLS errors.

Likely Cause

The app is using the customer console URL instead of the object storage endpoint, or TLS/DNS is not configured for the endpoint.

Fix

Use the S3-compatible storage endpoint. Do not use http://localhost:3000 unless your storage endpoint is actually running there.

Bucket Not Found

Symptom

SDK calls return NoSuchBucket.

Likely Cause

The app used a friendly display name instead of the actual bucket name, or the bucket belongs to another account.

Fix

Open the bucket in Quat and copy the real bucket name from bucket details.

Access Denied

Symptom

SDK calls return AccessDenied or InvalidAccessKeyId.

Likely Cause

The subscription is inactive, credentials were regenerated, or the key pair is wrong.

Fix

Check Billing and Settings > API Keys. Reveal or regenerate credentials and update application secrets.

CORS Issues

Symptom

Browser uploads or downloads fail with a CORS error.

Likely Cause

The bucket CORS policy does not allow the browser origin, method, or headers.

Fix

Open the bucket CORS tab and add a rule:

{
    "AllowedOrigins": ["https://app.example.com"],
    "AllowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"],
    "AllowedHeaders": ["*"],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 3600
}

Large File Upload Issues

Symptom

The console rejects a file upload.

Likely Cause

The selected file is empty or larger than the console upload limit.

Fix

The customer app limits console uploads to 5 GB. For larger files, confirm whether your storage deployment supports multipart uploads and use an SDK flow designed for multipart upload.

Path-Style Vs Virtual-Hosted-Style

Symptom

The SDK tries to call https://my-bucket.storage.example.local and fails DNS or TLS validation.

Likely Cause

The SDK is using virtual-hosted-style addressing.

Fix

Enable path-style addressing:

forcePathStyle: true;

Config(s3={"addressing_style": "path"})

"use_path_style_endpoint" => true

Laravel Issues

Symptom

Laravel says it cannot write a file, but the cause is unclear.

Fix

Enable thrown filesystem exceptions and clear cached config:

'throw' => true,

php artisan config:clear
php artisan cache:clear

Node.js Issues

Symptom

CredentialsProviderError or empty key errors.

Fix

Load environment variables before creating the S3 client and validate required values at startup.

if (!process.env.S3_ACCESS_KEY || !process.env.S3_SECRET_KEY) {
    throw new Error("Missing S3 credentials");
}

Python boto3 Issues

Symptom

NoCredentialsError.

Fix

Call load_dotenv() before constructing the boto3 client, or configure credentials in your deployment secret manager.

from dotenv import load_dotenv

load_dotenv()