This Docker build error occurs when you name a multi-stage build stage with a string that starts with a number. Docker stage names must begin with an alphabetic character and follow specific naming conventions.
The "stage name cannot start with a number" error occurs during Docker multi-stage builds when you attempt to name a build stage using the `FROM ... AS <name>` syntax with an invalid name. Docker enforces strict naming rules for build stages, and one key rule is that stage names must begin with an alphabetic character (a-z or A-Z). When Docker parses your Dockerfile, it validates each stage name against its naming rules. If you use a name like `1stage`, `2builder`, or `3rd-build`, Docker will reject it immediately with this error. The full error message is typically: "invalid name for build stage: name can't start with a number or contain symbols." This validation exists because stage names are used as references in subsequent instructions like `FROM <stage>`, `COPY --from=<stage>`, and `RUN --mount=type=bind,from=<stage>`. Having consistent naming rules ensures these references work reliably across different Docker versions and build tools.
Find the FROM instruction with the invalid stage name. Look for any stage name starting with a number:
Incorrect examples:
FROM node:18 AS 1builder
FROM golang:1.21 AS 2nd-stage
FROM python:3.11 AS 3buildRun the build with verbose output to see exactly which line fails:
docker build --progress=plain -t myapp .The error will indicate the problematic stage name in the message.
Change the stage name to start with an alphabetic character. Use descriptive names that begin with letters:
Before (invalid):
FROM node:18 AS 1builder
WORKDIR /app
COPY package*.json ./
RUN npm installAfter (valid):
FROM node:18 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm installIf you need to indicate ordering, use words instead of numbers:
FROM node:18 AS stage-one
# or
FROM node:18 AS first-builderAfter renaming a stage, update all instructions that reference it:
# Stage 1: Build
FROM node:18 AS builder
WORKDIR /app
COPY . .
RUN npm ci && npm run build
# Stage 2: Runtime
FROM nginx:alpine AS runtime
# Update the --from reference to match the new stage name
COPY --from=builder /app/dist /usr/share/nginx/htmlCheck for references in:
- FROM <stage> instructions
- COPY --from=<stage> instructions
- RUN --mount=type=bind,from=<stage> instructions
Use these guidelines for valid stage names:
Valid characters:
- Starts with: a-z, A-Z
- Contains: a-z, A-Z, 0-9, underscore (_), hyphen (-), period (.)
Valid examples:
FROM node:18 AS builder
FROM node:18 AS build_stage
FROM node:18 AS build-stage
FROM node:18 AS stage1 # Number at end is OK
FROM node:18 AS build.v2 # Period is OKInvalid examples:
FROM node:18 AS 1builder # Starts with number
FROM node:18 AS build@stage # Contains @
FROM node:18 AS build#1 # Contains #
FROM node:18 AS -builder # Starts with hyphenIf using ARG to create dynamic stage names, ensure the resolved value follows naming rules:
Problematic:
ARG VERSION=2
FROM node:18 AS ${VERSION}builder
# Resolves to "2builder" - invalid!Fixed:
ARG VERSION=2
FROM node:18 AS builder-v${VERSION}
# Resolves to "builder-v2" - valid!Or use a prefix:
ARG STAGE_NAME=stage1
FROM node:18 AS build-${STAGE_NAME}While Docker allows uppercase stage names, BuildKit (the modern build engine) requires lowercase when referencing stages. For maximum compatibility, use lowercase:
# Recommended: lowercase
FROM node:18 AS builder
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
# Works but may cause issues with BuildKit
FROM node:18 AS Builder
FROM nginx:alpine
# BuildKit requires lowercase reference even if defined uppercase
COPY --from=builder /app/dist /usr/share/nginx/htmlThe Docker documentation recommends lowercase stage names as a best practice.
Stage Naming Rules Summary:
Docker stage names must follow these rules:
1. Must start with an alphabetic character (a-z, A-Z)
2. Can contain alphanumeric characters, underscores, hyphens, and periods
3. Cannot contain special symbols (@, #, $, %, etc.)
4. Cannot start with a hyphen, underscore, or period
BuildKit Considerations:
When using BuildKit (default since Docker 23.0), stage names are case-insensitive for referencing but must be lowercase when used with --target flag or in Docker Compose:
# If stage is defined as "Builder", you must use lowercase
docker build --target=builder -t myapp .Referencing Stages by Index:
If you prefer not to name stages, you can reference them by index (0-based):
FROM node:18
WORKDIR /app
RUN npm install
FROM nginx:alpine
# Reference first stage by index 0
COPY --from=0 /app/dist /usr/share/nginx/htmlHowever, named stages are recommended for clarity and maintainability.
Multi-platform Builds:
When building multi-platform images with docker buildx, stage naming rules apply consistently across all platforms. Invalid stage names will fail on all target platforms.
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