Storage Provider Compatibility Guide

This document details S3-compatible storage provider compatibility with Litestream, including known limitations, required configuration, and tested configurations.

Overview

Litestream uses the AWS SDK v2 for S3-compatible storage backends. While most providers implement the S3 API, there are important differences in behavior that can affect Litestream's operation.

Provider-Specific Configuration

AWS S3 (Default)

Status: Fully supported (primary target)

yaml

replicas:
  - url: s3://bucket-name/path
    region: us-east-1

Notes:

No special configuration required
All features fully supported
Checksum validation enabled by default

Cloudflare R2

Status: Supported with default configuration

Known Limitations:

Strict concurrent upload limit (2-3 concurrent uploads max)
Does not support aws-chunked content encoding
Does not support request/response checksums

Configuration:

yaml

replicas:
  - url: s3://bucket-name/path?endpoint=https://ACCOUNT_ID.r2.cloudflarestorage.com
    access-key-id: your-access-key-id
    secret-access-key: your-secret-access-key

Automatic Defaults (applied when R2 endpoint detected):

sign-payload=true - Signed payloads required
concurrency=2 - Limits concurrent multipart upload parts
Checksums disabled automatically

Important: The endpoint must use https:// scheme for R2 detection to work.

Related issues: #948, #947, #940, #941

Backblaze B2 (S3-Compatible API)

Status: Supported with configuration

Known Limitations:

Requires signed payloads for all requests
Specific authentication endpoint required

Configuration:

yaml

replicas:
  - url: s3://bucket-name/path?endpoint=https://s3.REGION.backblazeb2.com&sign-payload=true&force-path-style=true
    access-key-id: your-key-id
    secret-access-key: your-application-key

Required Settings:

sign-payload=true - Required for B2 authentication
force-path-style=true - Required for bucket access
Endpoint format: https://s3.REGION.backblazeb2.com

Related issues: #918, #894

DigitalOcean Spaces

Status: Supported with configuration

Known Limitations:

Does not support aws-chunked content encoding
Signature requirements differ from AWS

Configuration:

yaml

replicas:
  - url: s3://bucket-name/path?endpoint=https://REGION.digitaloceanspaces.com&force-path-style=false
    access-key-id: your-spaces-key
    secret-access-key: your-spaces-secret

Notes:

Use virtual-hosted style paths (force-path-style=false)
Checksum features disabled automatically for custom endpoints

Related issues: #943

MinIO

Status: Fully supported

Configuration:

yaml

replicas:
  - url: s3://bucket-name/path?endpoint=https://your-minio-server:9000&force-path-style=true
    access-key-id: your-access-key
    secret-access-key: your-secret-key

Notes:

Works well with default settings
Force path style recommended for single-server deployments

Scaleway Object Storage

Status: Supported with configuration

Known Limitations:

MissingContentLength errors with streaming uploads
Requires Content-Length header

Configuration:

yaml

replicas:
  - url: s3://bucket-name/path?endpoint=https://s3.REGION.scw.cloud&force-path-style=true
    access-key-id: your-access-key
    secret-access-key: your-secret-key

Related issues: #912

Hetzner Object Storage

Status: Supported with configuration

Known Limitations:

InvalidArgument errors with default AWS SDK settings
Does not support aws-chunked content encoding
Requires signed payloads for all requests

Configuration:

yaml

replicas:
  - url: s3://bucket-name/path?endpoint=https://REGION.your-objectstorage.com&force-path-style=true
    access-key-id: your-access-key
    secret-access-key: your-secret-key

Filebase

Status: Supported with configuration

Known Limitations:

Authentication failures with default SDK settings after SDK v2 migration

Configuration:

yaml

replicas:
  - url: s3://bucket-name/path?endpoint=https://s3.filebase.com&force-path-style=true
    access-key-id: your-access-key
    secret-access-key: your-secret-key

Tigris

Status: Supported with configuration

Configuration:

yaml

replicas:
  - url: s3://bucket-name/path?endpoint=https://fly.storage.tigris.dev&force-path-style=true
    access-key-id: your-access-key
    secret-access-key: your-secret-key

Supabase Storage (S3-Compatible API)

Status: Supported (auto-detected)

Known Limitations:

Requires path-style URLs (force-path-style=true)
No S3 versioning support

Configuration:

yaml

replicas:
  - url: s3://bucket-name/path?endpoint=https://PROJECT_REF.supabase.co/storage/v1/s3
    access-key-id: your-s3-access-key
    secret-access-key: your-s3-secret-key

Automatic Defaults (applied when Supabase endpoint detected):

sign-payload=true - Signed payloads required
force-path-style=true - Path-style URLs required

Notes:

S3 access keys are generated in the Supabase dashboard under Storage > S3 Access Keys
Endpoint format: https://<PROJECT_REF>.supabase.co/storage/v1/s3

Related issues: #1133

Wasabi

Status: Supported

Configuration:

yaml

replicas:
  - url: s3://bucket-name/path?endpoint=https://s3.REGION.wasabisys.com
    access-key-id: your-access-key
    secret-access-key: your-secret-key

Google Cloud Storage (GCS)

Status: Fully supported (native client)

yaml

replicas:
  - url: gcs://bucket-name/path

Authentication:

Uses Application Default Credentials
Set GOOGLE_APPLICATION_CREDENTIALS environment variable
Or use workload identity on GCP

S3-Compatible XML API

Status: Supported with HMAC keys

yaml

replicas:
  - type: s3
    bucket: bucket-name
    path: database-name
    endpoint: https://storage.googleapis.com
    region: us-east-1
    force-path-style: true
    access-key-id: your-hmac-access-key
    secret-access-key: your-hmac-secret

Litestream automatically excludes Accept-Encoding from SigV4 signatures for Cloud Storage endpoints under the exact googleapis.com domain when storage is an exact segment of the first hostname label. This covers global, regional, locational, mTLS, and legacy upload and download endpoints while rejecting external lookalike domains.

Azure Blob Storage (ABS)

Status: Fully supported (native client)

yaml

replicas:
  - url: abs://container-name/path
    account-name: your-account-name
    account-key: your-account-key

Using SAS Token (for granular container-level access):

yaml

replicas:
  - url: abs://container-name/path
    account-name: your-account-name
    sas-token: "sv=2023-01-03&ss=b&srt=co&sp=rwdlacx..."

Or via environment variable: LITESTREAM_AZURE_SAS_TOKEN

Alternative Authentication:

SAS token: sas-token config or LITESTREAM_AZURE_SAS_TOKEN env var
Account key: account-key config or LITESTREAM_AZURE_ACCOUNT_KEY env var
Managed identity on Azure (via DefaultAzureCredential)

Authentication Priority: SAS token > Account key > Default credential chain

Alibaba Cloud OSS

Status: Supported (native client)

yaml

replicas:
  - url: oss://bucket-name/path?endpoint=oss-REGION.aliyuncs.com
    access-key-id: your-access-key-id
    access-key-secret: your-access-key-secret

SFTP

Status: Supported

yaml

replicas:
  - url: sftp://hostname/path
    user: username
    password: password  # or use key-path

Configuration Reference

S3 Query Parameters

Parameters with an alias accept both camelCase and hyphenated forms (e.g., forcePathStyle or force-path-style).

Parameter	Alias	Description	Default
`endpoint`		Custom S3 endpoint URL	AWS S3
`region`		AWS region	Auto-detected
`forcePathStyle`	`force-path-style`	Use path-style URLs	`false` (auto for custom endpoints)
`skipVerify`	`skip-verify`	Skip TLS verification	`false`
`signPayload`	`sign-payload`	Sign request payloads	`true`
`requireContentMD5`	`require-content-md5`	Require Content-MD5 header	`true`
`concurrency`		Multipart upload concurrency	`5`
`partSize`	`part-size`	Multipart upload part size in bytes	`5242880` (5MB)
`storageClass`	`storage-class`	Storage class for uploaded objects	None
`sseCustomerAlgorithm`	`sse-customer-algorithm`	SSE-C encryption algorithm	None
`sseCustomerKey`	`sse-customer-key`	SSE-C encryption key	None
`sseCustomerKeyMD5`	`sse-customer-key-md5`	SSE-C key MD5 checksum	None
`sseKmsKeyId`	`sse-kms-key-id`	KMS key for encryption	None

Provider Detection

Litestream automatically detects certain providers and applies appropriate defaults:

Provider	Detection Pattern	Applied Settings
Hetzner	`*.your-objectstorage.com`	`sign-payload=true`
Cloudflare R2	`*.r2.cloudflarestorage.com`	`sign-payload=true`, `concurrency=2`
Backblaze B2	`*.backblazeb2.com`	`sign-payload=true`, `force-path-style=true`
DigitalOcean	`*.digitaloceanspaces.com`	`sign-payload=true`
Scaleway	`*.scw.cloud`	`sign-payload=true`
Filebase	`s3.filebase.com`	`sign-payload=true`, `force-path-style=true`
Tigris	`*.tigris.dev`	`sign-payload=true`, `require-content-md5=false`
MinIO	host with port (not cloud provider)	`sign-payload=true`, `force-path-style=true`
Supabase	`*.supabase.co`	`sign-payload=true`, `force-path-style=true`
Google Cloud Storage	Exact `googleapis.com` suffix with a first-label `storage` segment	Excludes `Accept-Encoding` from SigV4 signatures

Troubleshooting

Common Errors

InvalidArgument: Unsupported content encoding: aws-chunked

Provider doesn't support AWS SDK v2 chunked encoding
Use a custom endpoint with automatic checksum disabling
Or explicitly disable checksums

SignatureDoesNotMatch

Try sign-payload=true in the URL
Verify credentials are correct
Check endpoint URL format

MissingContentLength

Provider requires Content-Length header
This is handled automatically for known providers

Too many concurrent uploads or timeout errors

Reduce concurrency: ?concurrency=2
Particularly important for Cloudflare R2

AccessDenied or authentication failures

Verify credentials
Check IAM/bucket permissions
For B2, ensure sign-payload=true

Debug Mode

Enable verbose logging to diagnose issues:

bash

LITESTREAM_DEBUG=1 litestream replicate ...

Or in configuration:

yaml

logging:
  level: debug

Testing Your Configuration

Test connectivity without starting replication:

bash

# List any existing backups
litestream snapshots s3://bucket/path?endpoint=...

# Perform a test restore (requires existing backup)
litestream restore -o /tmp/test.db s3://bucket/path?endpoint=...

Version Compatibility

Litestream v0.5.x: AWS SDK v2, improved provider compatibility
Litestream v0.4.x: AWS SDK v1, different authentication handling
Litestream v0.3.x: Legacy format — v0.5.x can restore from v0.3.x backups via ReplicaClientV3 interface

When upgrading from v0.3.x, v0.5.x can automatically restore from v0.3.x backups if no v0.4.x+ backup exists. The S3 backend implements ReplicaClientV3 to read the v0.3.x generations/{id}/snapshots/ and generations/{id}/wal/ directory structure. See REPLICA_CLIENT_GUIDE.md for details.

Validation Interval

Litestream supports periodic validation of replica integrity:

yaml

validation:
  interval: "5m"  # How often to validate; 0 disables

This runs Store.Validate() on a ticker, comparing local and remote positions. Can also be set per-replica via the validation-interval replica config key. and cannot restore backups created by v0.3.x. See the upgrade guide for migration instructions.

Reporting Issues

When reporting provider compatibility issues, please include:

Provider name and region
Litestream version (litestream version)
Full error message
Configuration (with credentials redacted)
Whether the issue is with replication, restore, or both

File issues at: GitHub Issues