Troubleshooting & FAQs

This page covers common error messages, network challenges, and registry-specific issues you may encounter when using image-syncer.

Common Log Errors

"Put manifest ... unknown blob error"

  • Symptom: During synchronization, the execution fails when uploading the manifest with an unknown blob error, even though previous layer uploads completed without issues.
  • Cause: This usually happens in older versions (prior to v1.1.0) due to stale metadata records cache files on the host disk, or when multiple syncer processes share the same record database.
  • Resolution: If you are using an older version, delete your local records cache files and restart the synchronization. In versions v1.1.0 and newer, local records tracking is disabled by default, which avoids this mismatch.

Network and Transfer Issues

"read: connection reset by peer"

  • Cause: The source or destination registry closed the TCP connection. This is often caused by registry rate limiting or traffic throttling on large transfers.
  • Resolution: Reduce parallel network connections by setting a lower --proc value (e.g., -p 2 or -p 3), and increase the retry limit using the --retries flag to let the tool recover when rate limits reset.

"TLS handshake timeout"

  • Cause: Heavy network traffic or high latency prevents the secure connection handshake from completing within the default network timeout window.
  • Resolution: Run image-syncer on a system with a closer network path to your target registry (for example, inside the same cloud VPC or region). Alternatively, reduce the concurrency parameter (--proc) to lower the network load.

"DIGEST_INVALID"

  • Cause: The destination registry calculated a different digest checksum than expected, indicating that an image layer or metadata payload was corrupted during network transit.
  • Resolution: Increase your --retries setting. image-syncer will re-download the affected layer and attempt the transfer again.

Registry-Specific Challenges

Alibaba Cloud Container Registry (ACR) Private Repositories

  • Symptom: Syncer fails with an ACR get tags failed error when attempting to copy an entire private ACR repository.
  • Cause: Querying and listing tags in a private ACR repository requires specialized API permissions that are not supported by standard Docker Registry V2 tag listing protocols.
  • Resolution: Instead of using repository-wide synchronization (which requires listing all tags), specify the target tags explicitly in your images.yaml configuration file:
# Do not use: registry.cn-hangzhou.aliyuncs.com/my-namespace/private-repo
# Instead, specify tags explicitly:
registry.cn-hangzhou.aliyuncs.com/my-namespace/private-repo:v1.0.0: "target-registry.com/my-namespace/private-repo"

"500 Internal Server Error" on Target Registry

  • Symptom: The tool receives a generic 500 Internal Server Error response from the target registry when writing the final image manifest.
  • Cause: The source container image is likely packaged using the obsolete and deprecated Docker Schema V1 manifest format. image-syncer does not convert Schema V1 manifests to Schema V2. Many modern registry engines (such as Harbor or newer cloud distribution engines) have dropped support for Schema V1 and will reject these uploads.
  • Resolution: Pull, retag, and push the source image using a modern Docker daemon to update its packaging to Schema V2 or OCI format before running image-syncer.

To review the full range of command-line options and run parameters, refer to the Command-Line Interface Reference.