How to fix unknown instruction: RUN in Docker

File encoding is the most common cause when Docker reports a seemingly valid instruction as "unknown."

In VS Code:
1. Open your Dockerfile
2. Look at the bottom-right status bar for the encoding (e.g., "UTF-8" or "UTF-16 LE")
3. If it's not "UTF-8", click on the encoding and select "Reopen with Encoding" → "UTF-8"
4. Then "Save with Encoding" → "UTF-8"

From the command line:

# Check current encoding
file Dockerfile

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

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

# Convert from UTF-16 to UTF-8
iconv -f UTF-16 -t UTF-8 Dockerfile > Dockerfile.tmp && mv Dockerfile.tmp Dockerfile

# Remove BOM if present (first 3 bytes of UTF-8 BOM)
sed -i '1s/^\xEF\xBB\xBF//' Dockerfile

Windows uses CRLF (\r\n) line endings, but Docker expects Unix-style LF (\n). CRLF can cause the carriage return to be interpreted as part of the instruction.

In VS Code:
1. Look at the bottom-right status bar for "CRLF" or "LF"
2. If it shows "CRLF", click it and select "LF"
3. Save the file

From the command line:

# Using dos2unix (install with apt/brew if needed)
dos2unix Dockerfile

# Or using sed
sed -i 's/\r$//' Dockerfile

# Or using tr
tr -d '\r' < Dockerfile > Dockerfile.tmp && mv Dockerfile.tmp Dockerfile

Check for CRLF:

# Shows ^M at end of lines if CRLF is present
cat -A Dockerfile | head -5

Prevent future issues with .gitattributes:

echo "Dockerfile text eol=lf" >> .gitattributes

When splitting a RUN command across multiple lines, each line (except the last) must end with a backslash (\). Missing backslashes cause the next line to be interpreted as a new instruction.

Incorrect:

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

Docker sees "apt-get" as an unknown instruction on line 2.

Correct:

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

Important rules:
- The backslash must be the LAST character on the line
- No spaces or tabs after the backslash
- Comments cannot appear after the backslash

Check for trailing spaces after backslashes:

# Find lines with backslash followed by spaces
grep -n '\\ \+$' Dockerfile

Copy-pasting from websites, PDFs, or word processors can introduce invisible characters that break parsing.

View hidden characters:

# Show all characters including non-printable ones
cat -A Dockerfile

# Or use hexdump to see exact bytes
hexdump -C Dockerfile | head -20

Look for:
- M-BM- prefix (UTF-8 BOM or special characters)
- ^M at end of lines (CRLF)
- Unexpected characters at line beginnings

Clean the file:

# Remove all non-ASCII characters (aggressive)
LC_ALL=C tr -cd '\11\12\15\40-\176' < Dockerfile > Dockerfile.clean
mv Dockerfile.clean Dockerfile

Best practice: If you suspect copy-paste issues, create a new file and manually retype the content rather than pasting.

Every shell command in a Dockerfile must be prefixed with RUN. Without it, Docker interprets the command name as an instruction.

Incorrect:

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

This causes "unknown instruction: apt-get".

Correct:

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

Better (combined for fewer layers):

FROM ubuntu:22.04
RUN apt-get update && \
    apt-get install -y nginx && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*

Common commands that need RUN:
- Package managers: apt-get, yum, dnf, apk, pip, npm
- File operations: mkdir, chmod, chown, rm, mv, cp
- Downloads: curl, wget
- Any shell command or script

Multiple files named "Dockerfile" with different cases can cause Docker to use the wrong file.

Find all Dockerfile variants:

find . -maxdepth 2 -iname "*dockerfile*" -type f

Common conflicts:
- Dockerfile and dockerfile (case difference)
- Dockerfile in current directory and .docker/Dockerfile
- Backup files like Dockerfile.bak or Dockerfile.old

Solutions:

1. Remove or rename conflicting files:

mv dockerfile dockerfile.backup

2. Explicitly specify which Dockerfile to use:

docker build -f ./Dockerfile -t myimage .

3. Use a subdirectory with a clear name:

docker build -f docker/production.Dockerfile -t myimage .

After making corrections, test your Dockerfile:

# Basic build test
docker build -t test-build .

# With BuildKit for better error messages
DOCKER_BUILDKIT=1 docker build -t test-build .

# Build with no cache to ensure fresh parsing
docker build --no-cache -t test-build .

Validate syntax without building (using hadolint):

# Run hadolint linter
docker run --rm -i hadolint/hadolint < Dockerfile

If the error persists:

1. Create a minimal test Dockerfile:

FROM alpine:latest
RUN echo "test"

2. If this works, add your original content line by line until you find the problematic line

3. Compare the problematic line byte-by-byte:

echo 'RUN apt-get update' | hexdump -C
# Compare with your file
sed -n 'Xp' Dockerfile | hexdump -C  # Replace X with line number