Docker "ONBUILD" Triggers Fire Unexpectedly in a Child Build in CI

ONBUILD instructions in a base image are deferred - they fire automatically when another Dockerfile uses that image as its FROM. A child build can fail on a COPY/RUN it never wrote, because the base image queued it with ONBUILD.

What this error means

A docker build fails on a step that is not in your Dockerfile (e.g. COPY . /usr/src/app), with a # 4 [2/4] ... ONBUILD marker. The failing instruction came from the base image’s ONBUILD triggers, not your file.

docker build output

#5 [2/4] ONBUILD COPY package.json /usr/src/app/
#5 ERROR: failed to compute cache key: "/package.json": not found
# your Dockerfile has no COPY for package.json - the base image's ONBUILD added it

Common causes

The base image defines ONBUILD instructions

Some "onbuild" base images queue COPY/RUN steps that execute in the child build. If your project layout does not match what they expect (e.g. a package.json at the root), the deferred step fails.

Inherited ONBUILD assumes a different context

The ONBUILD COPY assumes files at specific paths in your build context. A mismatched layout makes the inherited step fail before your own instructions run.

How to fix it

Match your context to the base image’s ONBUILD expectations

Provide the files the inherited ONBUILD steps expect, or switch to a non-onbuild base.

Terminal / Dockerfile

# inspect what triggers the base image queued:
docker image inspect node:onbuild --format '{{json .Config.OnBuild}}'
# then ensure the expected files exist, or use a plain base:
FROM node:20-slim

Avoid onbuild base images when you control the steps

Use an explicit base and write the COPY/RUN steps yourself for predictability.

Dockerfile

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

How to prevent it

Inspect a base image’s ONBUILD triggers before adopting it.
Prefer explicit COPY/RUN over onbuild base images for clarity.
Lay out the project to match any inherited ONBUILD expectations.