🚨 Docker Error Guide: 'Dockerfile parse error: unknown instruction' — Fix Invalid Dockerfile Syntax

Overview

The build fails immediately during the parse phase, before any layer runs, because the frontend hit a token it does not recognize as an instruction:

Dockerfile parse error line 7: unknown instruction: RUUN

The parser reads the first word of each logical line and matches it against the known instruction set (FROM, RUN, COPY, CMD, and so on). Anything else — a typo, a stray shell command, a misplaced flag, or prose accidentally saved into the file — becomes an “unknown instruction.”

Symptoms

• docker build aborts on the parse phase with a specific line number.
• No image layers are created; the build never reaches the first RUN.
• The reported line often contains a misspelled keyword (RUUN, COPPY, ENTRYPOIN) or a bare shell command like apt-get.
• Multi-line commands that lost their trailing \ report the next line as the unknown instruction.

Common Root Causes

• Typos in the instruction keyword — RUUN, FORM, EXPOSE misspelled.
• A missing line continuation — a RUN command wrapped across lines without a trailing backslash, so the second line’s first word (e.g. apt-get) is parsed as an instruction.
• Bare shell commands — pasting apt-get install curl on its own line instead of prefixing it with RUN.
• Wrong file entirely — pointing -f at a shell script or README that is not a Dockerfile.
• Smart-quote or hidden characters — copying from a blog or doc introduces a non-ASCII dash or quote.
• Leading whitespace confusion — while indentation is tolerated, a stray token before the keyword can break parsing.

Note: instruction keywords are case-insensitive (from works), so casing alone is not the cause — but convention is uppercase.

Diagnostic Workflow

Run the build and note the exact line number the parser rejects:

docker build -t myapp:1.4.2 .

Open that line and print the file with line numbers so the reported line lines up:

cat -n Dockerfile

If you use a non-default filename, confirm you are parsing the file you think you are:

docker build -f docker/Dockerfile.prod -t myapp:1.4.2 .

Check for hidden or non-ASCII characters that a plain cat hides:

cat -A Dockerfile | sed -n '5,9p'
grep -nP '[^\x00-\x7F]' Dockerfile

Validate structure with BuildKit’s dry parse — it stops at the same error without executing layers:

docker buildx build --call outline .

You can also lint the file client-side with the Dockerfile validator before ever invoking the daemon.

Example Root Cause Analysis

A team saw builds break after editing their Dockerfile:

Dockerfile parse error line 7: unknown instruction: apt-get

cat -n Dockerfile showed:

6  RUN apt-get update
7  apt-get install -y curl ca-certificates

Line 6 had lost its trailing backslash during a rebase. The parser treated line 7 as a new instruction, and apt-get is not one. The fix was to join them into a single instruction:

RUN apt-get update && \
    apt-get install -y curl ca-certificates

The build parsed cleanly on the next run. The lesson: an “unknown instruction” on a valid shell command almost always means the previous line dropped its \.

Prevention Best Practices

• Chain related shell steps with && and \ inside a single RUN to avoid orphaned lines and reduce layers.
• Lint every Dockerfile in CI with hadolint or the Dockerfile validator before building.
• Keep the # syntax=docker/dockerfile:1 directive at the top so you get modern, clearer BuildKit parse errors.
• Retype commands copied from web pages, or paste through a plain-text editor, to strip smart quotes and non-ASCII dashes.
• Use editor Dockerfile syntax highlighting; misspelled keywords lose their color immediately.

Quick Command Reference

docker build -t myapp:1.4.2 .            # build, note the parse line number
cat -n Dockerfile                        # inspect the reported line
cat -A Dockerfile                        # reveal hidden characters
grep -nP '[^\x00-\x7F]' Dockerfile       # find non-ASCII characters
docker build -f path/to/Dockerfile .     # parse the intended file

Conclusion

unknown instruction is a pure syntax error surfaced during parsing, so it is fast to fix once you read the exact line the daemon names. Look first for a typo in the keyword, then for a missing backslash on the line above, then for the wrong file being parsed. Linting Dockerfiles in CI catches every one of these before they reach a build agent. Explore more build and runtime fixes in the Docker stack guides.