This Docker build error occurs when the Dockerfile is empty, contains only comments, or cannot be read due to encoding issues. Docker requires at least one valid instruction (like FROM) to build an image.
The "file with no instructions" error is a Docker build error that indicates Docker's build engine (BuildKit) cannot find any valid instructions in your Dockerfile. This error occurs during the LLB (Low-Level Builder) definition phase, before any actual build steps execute. Docker requires every Dockerfile to contain at least one valid instruction, with the most fundamental being the FROM instruction that specifies the base image. When Docker parses your Dockerfile and finds no recognizable instructions, it raises this error. This error is distinct from syntax errors because Docker isn't finding malformed instructions - it's finding no instructions at all. Common causes include empty files, files containing only comments, encoding issues that make the content unreadable, or Docker looking at the wrong file entirely.
First, confirm your Dockerfile exists and contains actual instructions:
# Check file exists and show size
ls -la Dockerfile
# Display file contents
cat DockerfileYou should see instructions like FROM, RUN, COPY, etc. If the file is empty or shows nothing, you need to add content.
Minimum valid Dockerfile:
FROM alpine:latestA common cause is editing a Dockerfile but forgetting to save it. Check your text editor:
1. Look for unsaved file indicators (dot or asterisk in tab title)
2. Press Ctrl+S (Windows/Linux) or Cmd+S (Mac) to save
3. Re-run your Docker build command
In VS Code, check the bottom status bar - unsaved files show a dot next to the filename.
File encoding problems can make content invisible to Docker. Check and fix encoding:
# Check file encoding
file DockerfileExpected output: Dockerfile: ASCII text or Dockerfile: UTF-8 Unicode text
If you see UTF-16, UTF-32, or unusual encoding, convert it:
Using iconv:
iconv -f UTF-16 -t UTF-8 Dockerfile > Dockerfile.new
mv Dockerfile.new DockerfileIn VS Code:
1. Click the encoding in the bottom status bar (e.g., "UTF-16 LE")
2. Select "Save with Encoding"
3. Choose "UTF-8"
Windows uses CRLF line endings while Linux uses LF. This can cause parsing issues:
# Check for Windows line endings
cat -A Dockerfile | head -5If you see ^M at the end of lines, you have Windows line endings.
Fix with dos2unix:
dos2unix DockerfileFix with sed:
sed -i 's/\r$//' DockerfileFix in VS Code:
1. Click "CRLF" in the bottom status bar
2. Select "LF"
3. Save the file
Docker may be looking at a different file than you expect:
# List all Dockerfile variants in current directory
ls -la Dockerfile* dockerfile*Common naming issues:
- Linux is case-sensitive: dockerfile and Dockerfile are different files
- Docker defaults to Dockerfile (capital D)
- Hidden files: .Dockerfile won't be found
Explicitly specify the Dockerfile:
docker build -f ./Dockerfile -t myimage .For docker-compose, specify in your compose file:
services:
app:
build:
context: .
dockerfile: DockerfileOn Linux and WSL2, file permissions can prevent Docker from reading the Dockerfile:
# Check permissions
ls -la Dockerfile
# Fix permissions if needed
chmod 644 DockerfileWSL2 specific: Files copied directly from Windows Explorer to Ubuntu may have blank permissions:
# Recreate the file in WSL
cat Dockerfile > Dockerfile.new
mv Dockerfile.new DockerfileEnsure Docker can find your Dockerfile in the build context:
# Build from current directory (Dockerfile must be here)
docker build -t myimage .
# Build with explicit context path
docker build -t myimage -f /path/to/Dockerfile /path/to/contextCheck your current directory:
pwd
ls -la DockerfileMake sure you're in the directory containing your Dockerfile, or use the -f flag to specify its location.
If other solutions don't work, recreate the Dockerfile to eliminate any hidden issues:
# Backup existing file
mv Dockerfile Dockerfile.bak
# Create new file with known-good content
cat > Dockerfile << 'EOF'
FROM alpine:latest
CMD ["echo", "Hello World"]
EOF
# Test the build
docker build -t test .If this works, gradually copy your original instructions back, testing after each addition to identify which line causes problems.
Understanding the LLB Definition:
LLB (Low-Level Builder) is BuildKit's intermediate representation for build operations. When Docker parses your Dockerfile, it converts instructions into LLB operations. The "failed to create LLB definition" error means this conversion failed at the very first step - there was nothing to convert.
BuildKit vs Legacy Builder:
This specific error message is from BuildKit (Docker's modern build engine). The legacy builder shows a slightly different message: "failed to parse Dockerfile: file with no instructions". Both mean the same thing.
To test with the legacy builder:
DOCKER_BUILDKIT=0 docker build -t myimage .Editor-specific Issues:
- VS Code: May save as UTF-16 by default on some systems. Check encoding in the status bar.
- Notepad (Windows): Adds BOM (Byte Order Mark) to UTF-8 files. Use Notepad++ or VS Code instead.
- Vim: Use :set fileencoding=utf-8 and :set fileformat=unix before saving.
CI/CD Considerations:
If builds work locally but fail in CI:
1. Check how the Dockerfile is created (templating, copying from artifacts)
2. Verify the file exists in the build context
3. Check for encoding differences between local and CI environments
4. Ensure any secrets injection isn't corrupting the file
Docker Compose Specifics:
When using docker-compose, ensure each service with a build: section has access to a valid Dockerfile:
services:
app:
build:
context: ./app
dockerfile: Dockerfile # Must exist in ./app/dockerfile parse error line 5: unknown instruction: RRUN
How to fix 'unknown instruction' Dockerfile parse error in Docker
Error response from daemon: manifest for nginx:nonexistent not found: manifest unknown: manifest unknown
How to fix 'manifest for image:tag not found' in Docker
Error response from daemon: invalid reference format: repository name must be lowercase
How to fix 'repository name must be lowercase' in Docker
Error response from daemon: No such image
How to fix 'No such image' in Docker
Error response from daemon: Container is not running
How to fix 'Container is not running' when using docker exec