Client gotchas¶

AWS CLI ignores my endpoint¶

You must pass --endpoint-url "https://YOUR-ENDPOINT/" on each command (or script it via a wrapper). Without it, the CLI talks to AWS, not your node. See client examples.

rclone can't see my buckets¶

Check that your remote has endpoint set with https://, and add force_path_style = true. Without path-style, rclone may try bucket-prefixed hostnames.

s3cmd fails on bucket operations¶

Set both host_base and host_bucket to your endpoint hostname (no scheme) and use_https = True. A mismatch between those two values is the usual culprit.

Cyberduck shows certificate or host errors¶

Enter the endpoint hostname only (no https://) as the server, use your access key as the username and secret key as the password, and prefer path-style connect mode if offered.

My SDK uses virtual-host addressing and breaks¶

Force path-style. For boto3:

from botocore.config import Config
s3 = boto3.client("s3", endpoint_url="https://YOUR-ENDPOINT/",
                  config=Config(s3={"addressing_style": "path"}))

See Path-style vs virtual-host.

A tool demands a region and won't proceed¶

Enter us-east-1. It's a placeholder; the endpoint URL determines routing.

Scans or listings are slow¶

By default rclone makes one API call per directory, which is slow over a high-latency S3 endpoint when a tool walks a large library. Add --fast-list to direct commands (rclone lsf/ls/size/copy) — it reads the tree recursively in batched LIST calls (one per ~1000 objects). It costs ~1 KB RAM per object, so drop it on memory-constrained boxes.

On an rclone mount, on-demand browsing ignores --fast-list, so the first browse after a reboot crawls. Warm the VFS cache once after mounting — one non-recursive async refresh per top-level directory, so the walks run in parallel and stay light on the backend:

for d in /mnt/zendrive/*/; do
  rclone rc vfs/refresh dir="$(basename "$d")" recursive=false _async=true \
    --rc-addr 127.0.0.1:5572
done

This warms the top-level listings you browse — the production-proven default. For a boot-time service that warms several mounts safely, see Warming the rclone cache at startup. If you want the whole tree cached so a full library scan reads from memory, run a recursive deep prime once instead (recursive=true, which honors --fast-list) — heavier on a library the size of ZenDRIVE. See Mount for streaming.

A large download stalls partway¶

Retry — most clients resume from where they left off. Raising concurrency can also help. If a specific object consistently fails, open a support ticket.

My client tries to upload or create a bucket and fails¶

That's expected — ZenDRIVE S3 Access is read-only. Use list/download operations only; see Browsing & downloading.

My GUI client isn't listed here¶

If it supports a custom S3 endpoint plus access/secret keys and path-style addressing, it should work. Mirror the settings from the client examples.