Docker "unknown instruction" - Fix Stray Lines and Wrong Syntax

BuildKit read the first word of a line and did not recognize it as a Dockerfile instruction. Usually a shell command leaked onto its own line, outside a RUN.

What this error means

The build fails immediately with unknown instruction: <WORD>, naming the first token of a line. No steps run because the Dockerfile never parsed.

ERROR: failed to solve: dockerfile parse error on line 8: unknown instruction: NPM
# line 8 is:  NPM install   (a shell command that should be inside a RUN)

Common causes

A shell command placed outside a RUN

A line like npm install, apt-get update, or cd /app written on its own is read as a Dockerfile instruction. Its first word (NPM, APT-GET, CD) is not a known instruction.

A broken multi-line RUN continuation

A missing trailing backslash ends the RUN early, so the next line is parsed as a new instruction whose first word is unrecognized.

A leaked heredoc body or stray text

A heredoc whose terminator is misindented, or a block of pasted text, leaves shell lines at the top level where Docker expects instructions.

How to fix it

Wrap shell commands in a RUN

Anything that is a shell command must live inside a RUN, joined with && or backslash continuations.

# wrong:
# NPM install
# right:
RUN npm install && npm run build

Check the named line and its continuation

1. Open the Dockerfile at the line in the error and confirm the first word is a real instruction.
2. If it should be part of the previous RUN, add the missing backslash to the line above it.
3. Indent heredoc terminators correctly so the body is not left at the top level.

How to prevent it

• Lint Dockerfiles with hadolint to catch stray instructions before building.
• Keep multi-line RUN blocks tidy with one backslash per continued line.
• Never paste raw shell scripts directly into a Dockerfile outside a RUN.

Related guides