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

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:

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:

iconv -f UTF-16 -t UTF-8 Dockerfile > Dockerfile.fixed
mv Dockerfile.fixed Dockerfile

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):

dos2unix Dockerfile

If you don't have dos2unix:

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

Configure Git to handle line endings correctly:

# In your repository root
echo "* text=auto" > .gitattributes
echo "Dockerfile text eol=lf" >> .gitattributes

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

Incorrect:

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

Correct:

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

Or combine them:

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

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

Incorrect:

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

Correct:

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):

RUN <<EOF
apt-get update
apt-get install -y curl
apt-get clean
EOF

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:

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

Correct:

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

Or with proper continuation:

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

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/

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

Check for conflicting files:

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:

docker build -f Dockerfile.prod -t myapp:latest .

After making changes, test your Dockerfile:

docker build -t test-build .

Enable BuildKit for better error messages:

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:

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

This catches syntax errors and suggests best practices.