diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
index 42bf57bc8..02ff15988 100644
--- a/TROUBLESHOOTING.md
+++ b/TROUBLESHOOTING.md
@@ -3,6 +3,7 @@
 * [Cannot push to a registry](#cannot-push-to-a-registry)
   * [BuildKit container logs](#buildkit-container-logs)
   * [With containerd](#with-containerd)
+* [`repository name must be lowercase`](#repository-name-must-be-lowercase)
 
 ## Cannot push to a registry
 
@@ -14,9 +15,11 @@ While pushing to a registry, you may encounter these kinds of issues:
 * `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](https://github.com/docker/buildx),
-[buildkit](https://github.com/moby/buildkit), [containerd](https://github.com/containerd/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.
+These issues are not directly related to this action but are rather linked to
+[buildx](https://github.com/docker/buildx), [buildkit](https://github.com/moby/buildkit),
+[containerd](https://github.com/containerd/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
 
@@ -25,8 +28,9 @@ action step and attach BuildKit container logs to your issue.
 
 ### With containerd
 
-Next you can test pushing with [containerd action](https://github.com/crazy-max/ghaction-setup-containerd) using the
-following workflow. If it works then open an issue on [buildkit](https://github.com/moby/buildkit) repository.
+Next you can test pushing with [containerd action](https://github.com/crazy-max/ghaction-setup-containerd)
+using the following workflow. If it works then open an issue on [buildkit](https://github.com/moby/buildkit)
+repository.
 
 ```yaml
 name: containerd
@@ -69,3 +73,57 @@ jobs:
         run: |
           sudo ctr --debug i push --user "${{ secrets.DOCKER_USERNAME }}:${{ secrets.DOCKER_PASSWORD }}" docker.io/user/app:latest
 ```
+
+## `invalid reference format`
+
+You may encounter this issue if you're using `github.repository` in your tag
+name:
+
+```
+#10 importing cache manifest from ghcr.io/My-Org/repo:main
+#10 ERROR: invalid reference format: repository name must be lowercase
+```
+
+## `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](https://github.com/docker/metadata-action)
+to generate sanitized tags, or a dedicated step to sanitize the slug:
+
+```yaml
+- name: Sanitize repo slug
+  uses: actions/github-script@v4
+  id: repo_slug
+  with:
+    result-encoding: string
+    script: return `ghcr.io/${github.repository.toLowerCase()}`
+
+- name: Build and push
+  uses: docker/build-push-action@v2
+  with:
+    context: .
+    push: true
+    tags: ${{ steps.repo_slug.outputs.result }}:latest
+```