Fly.io "failed to fetch an image or build" in CI

By Kaveh Alemi·Latchkey

flyctl tried to obtain the deploy image and failed: either the referenced image could not be pulled, or the Dockerfile build returned an error. The build output above names the real cause.

What this error means

A flyctl deploy step fails with "Error: failed to fetch an image or build from source: ..." after the build or pull step.

Error: failed to fetch an image or build from source: error building: ...
exit code: 1

Common causes

The Dockerfile build failed

A step in the Dockerfile returned non-zero (a failed install, a missing file), so the image could not be built.

The referenced image cannot be pulled

When deploying a prebuilt image, a wrong tag or missing registry credentials makes the pull fail.

How to fix it

Read the build output and fix the Dockerfile

1. Scroll up to the first build error in the flyctl output.
2. Reproduce the build locally with docker build.
3. Fix the failing step, then redeploy.

docker build -t app . && flyctl deploy

Use a remote builder or correct image reference

Build on Fly's remote builder to avoid local Docker issues, or fix the image tag and registry credentials for a prebuilt image.

flyctl deploy --remote-only

How to prevent it

• Build the image locally or in CI before deploying.
• Pin a valid image tag and provide registry credentials.
• Use --remote-only to keep builds consistent.

Frequently asked questions

Related guides

References

• Terraform documentation
• GitHub Actions documentation