build-push-action/TROUBLESHOOTING.md

Troubleshooting

• Cannot push to a registry
  • BuildKit container logs
  • With containerd
• repository name must be lowercase
• Image not loaded

Cannot push to a registry

While pushing to a registry, you may encounter these kinds of issues:

• failed commit on ref "layer-sha256:...": invalid content digest in response: invalid checksum digest format
• failed commit on ref "layer-sha256:...": no response
• failed commit on ref "manifest-sha256:...": unexpected status: 400 Bad Request
• failed commit on ref "manifest-sha256:...": unexpected status: 401 Unauthorized
• unexpected response: 401 Unauthorized

These issues are not directly related to this action but are rather linked to Buildx, BuildKit, containerd or the registry on which you're pushing your image. The quality of error message depends on the registry and are usually not very informative.

BuildKit container logs

To help you solve this, you have to enable debugging in the setup-buildx action step and attach BuildKit container logs to your issue.

With containerd

Next you can test pushing with containerd action using the following workflow. If it works then open an issue on BuildKit repository.

name: containerd

on:
  push:

jobs:
  containerd:
    runs-on: ubuntu-latest
    steps:
      -
        name: Checkout
        uses: actions/checkout@v4
      -
        name: Set up QEMU
        uses: docker/setup-qemu-action@v3
      -
        name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
        with:
          buildkitd-flags: --debug
      -
        name: Set up containerd
        uses: crazy-max/ghaction-setup-containerd@v2
      -
        name: Build Docker image
        uses: docker/build-push-action@v6
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          tags: docker.io/user/app:latest
          outputs: type=oci,dest=/tmp/image.tar
      -
        name: Import image in containerd
        run: |
          sudo ctr i import --base-name docker.io/user/app --digests --all-platforms /tmp/image.tar          
      -
        name: Push image with containerd
        run: |
          sudo ctr --debug i push --user "${{ secrets.DOCKER_USERNAME }}:${{ secrets.DOCKER_PASSWORD }}" docker.io/user/app:latest          

repository name must be lowercase

You may encounter this issue if you're using github.repository as a repo slug in your tag:

#6 exporting to image
#6 exporting layers
#6 exporting layers 1.2s done
#6 exporting manifest sha256:b47f7dfb97b89ccd5de553af3c8cd94c4795884cbe5693e93946b1d95a7b1d12 0.0s done
#6 exporting config sha256:995e93fab8196893192f08a38deea6769dc4d98f86cf705eccc24ec96a3e271c 0.0s done
#6 ERROR: invalid reference format: repository name must be lowercase
------
 > exporting to image:
------
error: failed to solve: invalid reference format: repository name must be lowercase

or a cache reference:

#10 importing cache manifest from ghcr.io/My-Org/repo:main
#10 ERROR: invalid reference format: repository name must be lowercase

To fix this issue you can use our metadata action to generate sanitized tags:

- name: Docker meta
  id: meta
  uses: docker/metadata-action@v4
  with:
    images: ghcr.io/${{ github.repository }}
    tags: latest

- name: Build and push
  uses: docker/build-push-action@v6
  with:
    context: .
    push: true
    tags: ${{ steps.meta.outputs.tags }}

Or a dedicated step to sanitize the slug:

- name: Sanitize repo slug
  uses: actions/github-script@v6
  id: repo_slug
  with:
    result-encoding: string
    script: return 'ghcr.io/${{ github.repository }}'.toLowerCase()

- name: Build and push
  uses: docker/build-push-action@v6
  with:
    context: .
    push: true
    tags: ${{ steps.repo_slug.outputs.result }}:latest

Image not loaded

Sometimes when your workflows are heavy consumers of disk storage, it can happen that build-push-action declares that the built image is loaded, but then not found in the following workflow steps.

• You can use the following solution as workaround, to free space on disk before building docker image using the following workflow step

      # Free disk space
      - name: Free Disk space
        shell: bash
        run: |
          sudo rm -rf /usr/local/lib/android  # will release about 10 GB if you don't need Android
          sudo rm -rf /usr/share/dotnet # will release about 20GB if you don't need .NET          

• Another workaround can be to call docker/setup-buildx-action with docker driver

name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
with:
  driver: docker

More details in the related issue