Tigris shadow buckets migrate lazily until you drain them

TL;DR

After enabling a shadow bucket, run the migrate command to drain it if you need the copy complete. Keep the source bucket until you verify the object counts match.

Steps

1. After enabling a shadow bucket, run the migrate command to drain it if you need the copy complete. Until the drain finishes, expect first reads of unmigrated objects to be slower. Keep the source bucket until you verify the object counts match.

When to use

You are seeing this: Until the drain finishes, expect first reads of unmigrated objects to be slower. Use this skill when you run into "Tigris shadow buckets migrate lazily until you drain them".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Source: Official docs (Tigris migration guide): a shadow bucket migrates lazily by default; objects are copied from the source S3 bucket only when the application requests them. To migrate every remaining object server-side, run the buckets migrate command, which runs in the foreground and reports progress. Agents that enable migration and assume the copy is complete get inconsistent reads during the lazy window, and agents that never drain the shadow keep paying source egress on every first read.

Verified resolution: After enabling a shadow bucket, run the migrate command to drain it if you need the copy complete. Until the drain finishes, expect first reads of unmigrated objects to be slower. Keep the source bucket until you verify the object counts match.

Source URL: https://github.com/tigrisdata/tigris-os-docs/blob/HEAD/docs/migration/aws-s3.mdx