Dockerfile parse error
The Docker builder engine failed to parse the Dockerfile due to syntax typos, incorrect instruction keywords, or malformed formatting.
Usually happens because:
- ☑ Typo in Dockerfile instruction keyword
- ☑ Missing backslash inside multiline RUN
- ☑ Stray characters or space after backslash
🔍 Quick Checklist:
What is Dockerfile parse error?
This error occurs during the image build stage (e.g. running 'docker build') when the Dockerfile parser encounters syntax it cannot resolve. Common root causes include typing invalid instruction verbs (like using 'RUNN' instead of 'RUN'), placing comments incorrectly, or neglecting backslash line continuations inside multiline strings.
Common Causes
- Unknown instruction spelling typo: Typing invalid keywords (e.g. 'ADDD' or 'EXPOSEED' instead of 'ADD' or 'EXPOSE').
- Missing backslash continuation: Writing multi-line shell commands inside RUN instructions without connecting lines using '\'.
- Invalid instruction placement: Declaring build arguments or copying commands before the required 'FROM' instruction (except for 'ARG').
| Cause | Frequency |
|---|---|
| Instruction spelling typos | ⭐⭐⭐⭐⭐ |
| Missing backslash on multiline RUN | ⭐⭐⭐⭐ |
| Incorrect instruction order | ⭐⭐ |
Common Mistakes
- Leaving trailing spaces after a backslash (`\ `) line continuation. The parser will treat the whitespace as the escape target, breaking the continuation on the next line.
- Placing code comment symbols (`#`) inside multiline RUN commands without breaking them into single command lines.
How to Fix
Docker Operations & Verification
Ensure backslash characters connect multiline shell blocks safely without trailing whitespaces.
# Wrong: missing backslash on line 2
RUN apt-get update && apt-get install -y \
curl
git # Throws unknown instruction 'git'
# Correct
RUN apt-get update && apt-get install -y \
curl \
gitPlatform Specific Fixes
Verifying Dockerfile compilation path parameters on Linux hosts.
docker build -f Dockerfile -t my-app:v1.0 .Best Practices
- Install Docker extensions inside your IDE (such as VS Code's Docker extension) to enable live syntax linting.
- Utilize automated linters (like Hadolint) to check Dockerfile syntax rules in code pipelines.
Frequently Asked Questions (FAQ)
Q: What is a Dockerfile parse error?
It is a syntax error thrown by the builder engine when a Dockerfile line violates grammatical conventions or contains invalid keywords.
Q: Can I declare ARG before FROM?
Yes. 'ARG' is the only instruction allowed to precede the 'FROM' instruction, typically used to declare base image version variables.
Q: How do I split a RUN instruction into multiple lines?
End each line except the last with a backslash ('\'), ensuring there are no trailing whitespace characters after the backslash.
Q: Why do I get 'unknown instruction' on comments?
Because you placed a comment prefix (#) inside a multi-line RUN command without escaping it, causing the parser to treat the next line as a fresh instruction.