How to fix image with reference was found but does not match the specified platform in Docker

# Using Docker buildx to inspect manifest
docker buildx imagetools inspect nginx:latest

# Example output shows supported platforms:
# Name:      docker.io/library/nginx:latest
# MediaType: application/vnd.docker.distribution.manifest.list.v2+json
# Digest:    sha256:abc123...
#
# Manifests:
#   Name:      docker.io/library/nginx:latest@sha256:...
#   Platform:  linux/amd64
#   Name:      docker.io/library/nginx:latest@sha256:...
#   Platform:  linux/arm64
#   Platform:  linux/arm/v7

# Using manifest inspect (requires experimental features)
docker manifest inspect mysql:5.7

# Check your system's architecture
docker info --format '{{.OSType}}/{{.Architecture}}'
# Example: linux/arm64

# Search for arm64-specific image variants
# Many images have architecture-specific tags or repos:
# - arm64v8/nginx instead of nginx
# - mysql:8.0-arm64 instead of mysql:8.0
# - library/alpine (multi-arch) vs alpine/armhf

# Official images on Docker Hub usually support multiple architectures
# Check the "Tags" tab on Docker Hub for architecture-specific tags

# Now you can pull and run amd64 images on ARM:
docker pull --platform linux/amd64 your-image:tag
docker run --platform linux/amd64 your-image:tag

# The image runs under emulation (slower but functional)

# Install QEMU for cross-architecture emulation
docker run --privileged --rm tonistiigi/binfmt --install all

# Verify emulation is available
cat /proc/sys/fs/binfmt_misc/qemu-x86_64

# Now pull and run with platform specification
docker run --platform linux/amd64 your-image:tag

# Create a new builder for multi-platform builds
docker buildx create --name multibuilder --use --bootstrap

# Build for multiple platforms and push to registry
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --tag your-registry/your-image:latest \
  --push \
  .

# Verify the multi-arch manifest was created
docker buildx imagetools inspect your-registry/your-image:latest

# Use a multi-arch base image
FROM --platform=$TARGETPLATFORM node:20-alpine

# Architecture-aware package installation
ARG TARGETARCH
RUN if [ "$TARGETARCH" = "arm64" ]; then \
      echo "Installing ARM64 packages"; \
    else \
      echo "Installing AMD64 packages"; \
    fi

# docker-compose.yml
version: '3.8'
services:
  legacy-app:
    image: old-image:latest
    platform: linux/amd64  # Force amd64 with emulation
    ports:
      - "8080:8080"

  modern-app:
    image: new-image:latest
    # No platform specified - uses native architecture
    ports:
      - "3000:3000"

# Run with explicit platform override
DOCKER_DEFAULT_PLATFORM=linux/amd64 docker-compose up

# Remove cached image data
docker image rm your-image:tag

# Clear buildx cache
docker buildx prune -f

# Pull fresh with explicit platform
docker pull --platform linux/arm64 your-image:tag

# If using a private registry, the registry itself may cache old manifests
# Contact your registry admin or wait for cache expiration

# Clone the original Dockerfile (usually on GitHub)
git clone https://github.com/original/image-repo
cd image-repo

# Create multi-platform builder
docker buildx create --name mybuilder --use

# Build for your needed platforms
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --tag your-dockerhub/forked-image:latest \
  --push \
  .

# docker-compose.yml
services:
  app:
    # image: abandoned/old-image:latest  # Old single-arch
    image: your-dockerhub/forked-image:latest  # Your multi-arch fork