When working with Docker and deploying your applications to Heroku, you might run into this cryptic message:
error from registry: unsupported
unsupported
Error: docker push exited with Error: 1
This error can be confusing and frustrating — especially since it gives very little detail. In this blog post, we’ll break down what this error means, why it happens, and how to fix it step by step.
The Error
If you’re trying to push your Docker image to Heroku’s container registry using a command like:
docker push registry.heroku.com/your-app-name/web
And you see:
error from registry: unsupported
unsupported
Error: docker push exited with Error: 1
It means that Heroku does not support the format or architecture of your Docker image.
Why This Happens
There are two common reasons this error occurs:
1. Wrong Platform Architecture
If you’re using a Mac with an Apple Silicon (M1/M2) chip or building images using Docker Buildx, you might be generating an image for the linux/arm64
platform — but Heroku only supports linux/amd64
.
2. Image Format Not Supported
Heroku expects Docker images in a traditional Docker V2 format. Sometimes, using tools like Docker Buildx can create images in an OCI (Open Container Initiative) format, which Heroku’s registry doesn’t recognize.
How to Fix It
Step 1: Set the Platform to linux/amd64
Before building the image, force Docker to use the architecture Heroku supports:
On Mac/Linux (bash):
export DOCKER_DEFAULT_PLATFORM=linux/amd64
On Windows PowerShell:
$env:DOCKER_DEFAULT_PLATFORM = "linux/amd64"
This tells Docker to use the amd64
architecture even if your machine uses ARM.
Step 2: Build the Docker Image
Use the standard Docker build command without buildx:
docker build --platform linux/amd64 -t registry.heroku.com/your-app-name/web .
This ensures your image uses the correct platform and format.
Step 3: Log in to Heroku Container Registry
If you haven’t already, log in:
heroku container:login
Step 4: Push the Image
Now push the image to Heroku:
docker push registry.heroku.com/your-app-name/web
You should no longer see the “unsupported” error.
Step 5: Release the Image
After pushing successfully, release it on Heroku:
heroku container:release web --app your-app-name
Optional: Test Locally Before Pushing
You can also test your Docker image locally to ensure it runs as expected:
docker run -p 5000:5000 registry.heroku.com/your-app-name/web
Still Seeing Issues?
Double-check:
- Your Docker version is up to date.
- You’re not using
buildx
or experimental Docker features. - Your image is tagged properly (
registry.heroku.com/your-app-name/web
).
Summary
Problem | Solution |
---|---|
error from registry: unsupported |
Use --platform linux/amd64 during build |
Heroku rejects image | Avoid buildx or OCI image formats |
You’re using an M1/M2 Mac | Set DOCKER_DEFAULT_PLATFORM=linux/amd64 |