mc replicate resync-backlog

The mc replicate resync-backlog command triggers replication for backlogged objects by performing HeadObject operations on each unreplicated version.

Use this command when replication is stuck or when you need to manually trigger replication for objects with PENDING or FAILED replication status.

Syntax

Example

The following command triggers replication for all backlogged objects in the mybucket bucket on the myaistor alias:

mc replicate resync-backlog myaistor/mybucket

The command displays a progress indicator showing the number of objects processed, failed, and skipped.

Syntax

The command has the following syntax:

mc [GLOBALFLAGS] replicate resync-backlog  \
                 [--arn "string"]          \
                 [--concurrent int]        \
                 [--rate-limit int]        \
                 [--dry-run]               \
                 [--clear-checksum]        \
                 [--validate]              \
                 TARGET

Brackets [] indicate optional parameters.
Parameters sharing a line are mutually dependent.
Parameters separated using the pipe | operator are mutually exclusive.

Copy the example to a text editor and modify as-needed before running the command in the terminal/shell.

Parameters

TARGET

Required

The alias, bucket, and optional prefix path for which to trigger replication of backlogged objects.

For example: myaistor/mybucket or myaistor/mybucket/path/to/prefix

--arn

Optional

The Amazon Resource Name (ARN) of a specific replication target.

When specified, the command only processes objects with PENDING or FAILED replication status for that specific target. If not specified, the command processes objects that are backlogged for any replication target.

--clear-checksum

Optional

When specified, clears object checksums by copying objects to themselves. Use this to correct checksum related replication failures.

--concurrent, -c

Optional

The number of concurrent HeadObject operations to perform.

Default: 10

--rate-limit

Optional

The maximum number of objects to process per second.

Set to 0 for unlimited processing rate.

Default: 0 (unlimited)

--validate

Optional

Test checksum clearing on a single object and exit without processing the full backlog. Use this with --clear-checksum to verify the operation works before running it on all objects.

--dry-run

Optional

Preview which objects would be processed without actually triggering replication.

Use this flag to estimate the scope of backlogged objects before running the actual resync operation.

Global flags

This command supports any of the global flags.

Examples

Trigger replication for all backlogged objects

The following command triggers replication for all objects with PENDING or FAILED replication status in a bucket:

mc replicate resync-backlog myaistor/mybucket

The command outputs progress information:

✓ Replication trigger completed
  Total: 150
  Processed: 148
  Failed: 2

⚠ Some objects failed to trigger replication.
  You can re-run this command to retry failed objects:
  $ mc replicate resync-backlog myaistor/mybucket

Trigger replication for a specific prefix

The following command triggers replication for backlogged objects within a specific prefix:

mc replicate resync-backlog myaistor/mybucket/path/to/prefix

Preview backlogged objects

The following command shows which objects would be processed without actually triggering replication:

mc replicate resync-backlog myaistor/mybucket --dry-run

Use this to estimate the scope of backlogged objects before running the actual operation.

Clear checksums to fix replication failures

The following command clears object checksums by copying objects to themselves, which can fix checksum-related replication failures:

mc replicate resync-backlog myaistor/mybucket --clear-checksum

Validate checksum clearing before full run

The following command tests checksum clearing on a single object before processing the full backlog:

mc replicate resync-backlog myaistor/mybucket --clear-checksum --validate

If validation succeeds, run again without --validate to process all backlogged objects.

Required permissions

This command requires the admin:ReplicationDiff permission on the target bucket.

Behavior

How replication triggering works

The command works by performing a HeadObject operation on each backlogged object version. This operation signals the AIStor server to re-queue the object for replication.

The command:

Fetches the list of objects with PENDING or FAILED replication status using the replication diff API.
Performs a HeadObject request on each object version to trigger replication.
Reports progress and any failures.

Large backlogs can generate high request volumes

By default, this command processes objects with 10 concurrent HeadObject operations and no rate limit. For large backlogs, this can generate significant request traffic that may impact cluster performance.

Use the --rate-limit flag to throttle the request rate and --concurrent to reduce parallel operations. For example, to limit to 5 concurrent operations at 20 objects per second:

mc replicate resync-backlog myaistor/mybucket --concurrent 5 --rate-limit 20

Use --dry-run first to assess the size of the backlog before processing.

Delete markers

Delete markers return HTTP 405 (Method Not Allowed) when performing HeadObject. The command treats this as a successful trigger because the replication process is still initiated server-side.

Retrying failed objects

If some objects fail to trigger, you can re-run the command. The command only processes objects that still have PENDING or FAILED replication status, so previously successful objects are not reprocessed.

S3 compatibility

The mc command-line tool is built for compatibility with the AWS S3 API and is tested with AIStor and AWS S3 for expected functionality and behavior.

MinIO provides no guarantees for other S3-compatible services, as their S3 API implementation is unknown and therefore unsupported.

While mc commands may work as documented, any such usage is at your own risk.