Docker "ONBUILD trigger failed" build error in CI

By Kaveh Alemi·Latchkey

An ONBUILD instruction baked into a base image runs automatically when a child image is built FROM it. If the child build does not provide what the trigger expects - a source file to COPY, a package manifest to install - the trigger fails inside the downstream build even though the child Dockerfile looks innocent.

What this error means

A build fails right after the FROM line with an error from an instruction the child Dockerfile never wrote. The base image carries ONBUILD triggers.

# Executing 1 build trigger
ERROR: failed to solve: failed to compute cache key: "/usr/src/app/package.json": not found
# the base image had: ONBUILD COPY package.json /usr/src/app/

Common causes

The child build lacks a file the trigger copies

An ONBUILD COPY package.json ... in the base fails if the child context has no package.json.

The trigger assumes a context layout you did not provide

ONBUILD RUN/COPY encode expectations about the downstream build context that the child must satisfy.

How to fix it

Provide what the ONBUILD trigger expects

1. Inspect the base image triggers, then add the required files to the child context.

docker inspect --format '{{.Config.OnBuild}}' node:onbuild
# then ensure the expected files exist in your build context

Switch to a base image without ONBUILD

1. Use a plain base and write the COPY/RUN steps explicitly in your Dockerfile.

FROM node:20-alpine
WORKDIR /usr/src/app
COPY package.json package-lock.json ./
RUN npm ci

How to prevent it

• Know the ONBUILD triggers of any base image you extend.
• Prefer explicit COPY/RUN over ONBUILD-laden base images.
• Provide every file the triggers expect in the child context.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation