How to fix dockerfile parse error line X: unknown instruction in Docker

DockerBEGINNERLOWUpdated Dec 6, 2025· 245 views

This error occurs when Docker encounters an unrecognized command or malformed syntax in your Dockerfile. Common causes include file encoding issues, missing RUN prefixes, incorrect line continuations, or Windows line endings (CRLF vs LF).

Quick fix

Fixes dockerfile parse error line X: unknown instruction

file Dockerfile
  1. Check file encoding
  2. Fix line endings (CRLF to LF)
  3. Add RUN prefix to shell commands
  4. Fix line continuation syntax
docker — error
file Dockerfile
dockerfile parse error line X: unknown instruction

What this error means

When you run `docker build`, Docker parses your Dockerfile line by line to understand what instructions to execute. Docker recognizes a specific set of valid instructions like FROM, RUN, COPY, CMD, ENTRYPOINT, WORKDIR, etc. as defined in the official Dockerfile reference. The "unknown instruction" error means Docker encountered text that doesn't match any valid Dockerfile instruction. This typically happens when: - You've used a shell command directly without the RUN prefix - Your file has encoding issues (like UTF-16 BOM or CRLF line endings) - You've made a syntax error with line continuations (backslashes) - You have extra line breaks splitting an instruction - There's a typo in an instruction name Docker is strict about Dockerfile syntax for good reason—a single typo or formatting issue can completely change how your container is built, potentially introducing security vulnerabilities or broken deployments.

Typical symptoms

  • Build fails immediately with 'dockerfile parse error line X: unknown instruction: COMMAND'
  • Error mentions instructions like 'apt-get', 'yum', 'npm' as unknown (should be prefixed with RUN)
  • Error shows garbled characters like '��F R O M' (encoding issue)
  • Build worked on Linux but fails on Windows (or vice versa) due to line endings
  • Syntax highlighting in your editor looks correct but build still fails
  • Error appears after copying a Dockerfile from a web page or documentation

Common causes

  1. Using shell commands directly without RUN prefix (e.g., 'apt-get install' instead of 'RUN apt-get install')
  2. File saved with wrong encoding (UTF-16 with BOM instead of UTF-8)
  3. Windows line endings (CRLF) instead of Unix line endings (LF)
  4. Missing backslash (\) for line continuation in multi-line commands
  5. Extra or unintended line breaks splitting a single instruction
  6. Typo in instruction name (e.g., 'WRKDIR' instead of 'WORKDIR')
  7. Multiple Dockerfiles in the project with conflicting names (Dockerfile vs dockerfile)
  8. Missing space between instruction and arguments (e.g., 'CMD["java"]' instead of 'CMD ["java"]')

How to fix "dockerfile parse error line X: unknown instruction"

1Check file encoding

File encoding issues are a common cause, especially if you're using VS Code or copying from web pages.

Check encoding in VS Code:
1. Open your Dockerfile
2. Look at the bottom-right corner of VS Code
3. It should say "UTF-8"
4. If it says "UTF-16 LE" or has "BOM", click it and select "Save with Encoding" → "UTF-8"

Check encoding from command line:

bash
file Dockerfile

Should output: Dockerfile: ASCII text or Dockerfile: UTF-8 Unicode text

If you see UTF-16, UTF-16 LE, or with BOM, convert it:

bash
iconv -f UTF-16 -t UTF-8 Dockerfile > Dockerfile.fixed
mv Dockerfile.fixed Dockerfile
2Fix line endings (CRLF to LF)

Windows uses CRLF (\r\n) line endings while Linux/Docker expects LF (\n). This is especially common when editing on Windows.

Check line endings in VS Code:
1. Look at the bottom-right corner
2. It should say "LF"
3. If it says "CRLF", click it and select "LF"

Convert line endings from command line (Windows):

bash
dos2unix Dockerfile

If you don't have dos2unix:

bash
sed -i 's/\r$//' Dockerfile

Configure Git to handle line endings correctly:

bash
# In your repository root
echo "* text=auto" > .gitattributes
echo "Dockerfile text eol=lf" >> .gitattributes
3Add RUN prefix to shell commands

Docker instructions must be valid Dockerfile commands. Shell commands need to be prefixed with RUN.

Incorrect:

dockerfile
FROM ubuntu:22.04
apt-get update
apt-get install -y curl

Correct:

dockerfile
FROM ubuntu:22.04
RUN apt-get update
RUN apt-get install -y curl

Or combine them:

dockerfile
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y curl

Common commands that need RUN:
- apt-get, apt
- yum, dnf
- npm install
- pip install
- curl, wget
- Any shell command

4Fix line continuation syntax

Multi-line commands require a backslash (\) at the end of each line to continue to the next.

Incorrect:

dockerfile
RUN apt-get update
    apt-get install -y curl
    apt-get clean

Correct:

dockerfile
RUN apt-get update && \
    apt-get install -y curl && \
    apt-get clean

Important rules:
- Backslash must be the LAST character on the line (no spaces after)
- The backslash escapes the newline character
- Proper indentation improves readability but isn't required

For complex multi-line content, use heredoc (requires BuildKit):

dockerfile
RUN <<EOF
apt-get update
apt-get install -y curl
apt-get clean
EOF
5Remove extra line breaks

Unintended line breaks can split an instruction into multiple lines, causing Docker to interpret part of the command as a new instruction.

Check for:
- Blank lines within a command
- Line breaks inside JSON arrays for CMD/ENTRYPOINT

Incorrect:

dockerfile
CMD[
  "java",
  "-jar",
  "app.jar"
]

Correct:

dockerfile
CMD ["java", "-jar", "app.jar"]

Or with proper continuation:

dockerfile
CMD ["java", \
     "-jar", \
     "app.jar"]
6Check for typos in instruction names

Verify all instruction names are spelled correctly. Docker is case-insensitive for instructions, but typos will cause parse errors.

Valid Dockerfile instructions:
- FROM - Base image
- RUN - Execute command
- CMD - Default command
- COPY / ADD - Copy files
- WORKDIR - Set working directory
- ENV - Set environment variable
- EXPOSE - Expose port
- ENTRYPOINT - Configure container executable
- LABEL - Add metadata
- ARG - Build-time variable
- USER - Set user
- VOLUME - Create mount point

Common typos:
- WRKDIR → WORKDIR
- ENVIROMENT → ENV
- EXPOSE_PORT → EXPOSE

Reference: https://docs.docker.com/engine/reference/builder/

7Check for multiple Dockerfile conflicts

If you have multiple files with "Dockerfile" in the name, Docker might pick up the wrong one.

Check for conflicting files:

bash
find . -iname "*dockerfile*"

Common conflicts:
- Dockerfile (primary)
- dockerfile (lowercase - can conflict on case-insensitive filesystems)
- Dockerfile.new, Dockerfile.backup
- Dockerfile in subdirectories

Fix:
- Rename backup/alternate Dockerfiles to not start with "Dockerfile"
- Use specific Dockerfile with -f flag:

bash
docker build -f Dockerfile.prod -t myapp:latest .
8Verify the fix

After making changes, test your Dockerfile:

bash
docker build -t test-build .

Enable BuildKit for better error messages:

bash
DOCKER_BUILDKIT=1 docker build -t test-build .

BuildKit provides clearer error messages and supports advanced features like heredocs.

Validate syntax without building:

Use a Dockerfile linter like hadolint:

bash
docker run --rm -i hadolint/hadolint < Dockerfile

This catches syntax errors and suggests best practices.

Advanced notes

### BuildKit and Advanced Syntax

Docker BuildKit (enabled with DOCKER_BUILDKIT=1) supports enhanced syntax features:

Heredoc syntax for multi-line commands:

dockerfile
# syntax=docker/dockerfile:1.4
RUN <<EOF
apt-get update
apt-get install -y curl wget
apt-get clean
rm -rf /var/lib/apt/lists/*
EOF

Multi-line COPY with heredoc:

dockerfile
COPY <<EOF /app/config.json
{
  "key": "value",
  "nested": {
    "data": true
  }
}
EOF

Enable BuildKit by default by adding to ~/.docker/daemon.json:

json
{
  "features": {
    "buildkit": true
  }
}

### IDE and Editor Configuration

VS Code:
Install the "Docker" extension for syntax highlighting and validation.

Configure default line endings:
Add to .vscode/settings.json:

json
{
  "files.eol": "\n",
  "[dockerfile]": {
    "files.encoding": "utf8"
  }
}

EditorConfig:
Create .editorconfig in your project root:

ini
[Dockerfile*]
end_of_line = lf
charset = utf-8
insert_final_newline = true

### Platform-Specific Notes

Windows:
When working with Docker on Windows (Docker Desktop), always use LF line endings for Dockerfiles, even though Windows natively uses CRLF. Configure Git:

bash
git config --global core.autocrlf input

macOS:
Encoding issues are less common on macOS, but check if copying from web pages or MS Word.

### Debugging Complex Parse Errors

If you're still getting parse errors after trying the basic fixes:

1. Create a minimal Dockerfile and test:

dockerfile
FROM alpine:latest
RUN echo "test"

2. Add instructions back one at a time until you find the problematic line

3. Check hidden characters:

bash
cat -A Dockerfile

Look for ^M (indicates CRLF) or unusual characters

4. Compare with a working Dockerfile from the same environment

Frequently asked questions

What does "dockerfile parse error line X: unknown instruction" mean?
When you run docker build, Docker parses your Dockerfile line by line to understand what instructions to execute. Docker recognizes a specific set of valid instructions like FROM, RUN, COPY, CMD, ENTRYPOINT, WORKDIR, etc. as defined in the official Dockerfile reference.
How do I fix "dockerfile parse error line X: unknown instruction"?
This error occurs when Docker encounters an unrecognized command or malformed syntax in your Dockerfile. Common causes include file encoding issues, missing RUN prefixes, incorrect line continuations, or Windows line endings (CRLF vs LF).
What causes "dockerfile parse error line X: unknown instruction"?
Using shell commands directly without RUN prefix (e.g., 'apt-get install' instead of 'RUN apt-get install') File saved with wrong encoding (UTF-16 with BOM instead of UTF-8) Windows line endings (CRLF) instead of Unix line endings (LF)
Is the "dockerfile parse error line X: unknown instruction" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading