Skaffold "image not found in artifacts" on deploy in CI

By Kaveh Alemi·Latchkey

When you split build and deploy across steps, Skaffold reads a build-artifacts file that maps image names to pushed tags. If the manifest references an image name not present in that file, the deploy fails because Skaffold has no tag to substitute.

What this error means

A skaffold deploy --build-artifacts step fails with "image X not found in the artifacts" or "loading artifacts: ...", so the manifest image is not rewritten.

loading artifacts: image "my-app" not found in the build artifacts file;
provide it with --build-artifacts or run build first

Common causes

A default-repo mismatch between build and deploy

The build step used a --default-repo that renamed the image, but the deploy step used a different (or no) default-repo, so names no longer line up.

The build-artifacts file was not passed or is stale

The deploy did not receive the --build-artifacts file from the build step, so it has no record of the pushed tag.

How to fix it

Pass the same file and default-repo across steps

1. Write the build output with --file-output in the build step.
2. Pass that file with --build-artifacts to the deploy step.
3. Use the same --default-repo in both steps so image names match.

skaffold build --file-output=build.json --default-repo=us-docker.pkg.dev/my-project/my-repo
skaffold deploy --build-artifacts=build.json --default-repo=us-docker.pkg.dev/my-project/my-repo

Persist build.json between jobs

If build and deploy run in separate jobs, upload build.json as an artifact and download it before deploy.

- uses: actions/upload-artifact@v4
  with:
    name: build-json
    path: build.json

How to prevent it

• Use one --default-repo value consistently across build and deploy.
• Always pass the --file-output file to --build-artifacts on deploy.
• Persist build.json when build and deploy run in separate jobs.

Frequently asked questions

Related guides

References

• Kubernetes documentation
• GitHub Actions documentation