How to fix invalid stage name: stage name cannot start with a number in Docker

DockerBEGINNERLOWUpdated Dec 6, 2025· 135 views

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.

Quick fix

Fixes invalid stage name: stage name cannot start with a number

FROM node:18 AS 1builder
FROM golang:1.21 AS 2nd-stage
FROM python:3.11 AS 3build
  1. Identify the invalid stage name
  2. Rename the stage with a letter prefix
  3. Update all references to the renamed stage
  4. Follow Docker stage naming conventions
docker — error
FROM node:18 AS 1builder
FROM golang:1.21 AS 2nd-stage
FROM python:3.11 AS 3build
invalid stage name: stage name cannot start with a number

What this error means

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.

Typical symptoms

  • Docker build fails immediately with 'invalid stage name' error
  • Error message mentions 'name can't start with a number or contain symbols'
  • Multi-stage Dockerfile builds that previously worked fail after renaming stages
  • Build fails at the FROM instruction where the invalid stage name is defined
  • CI/CD pipeline fails during Docker build step with stage naming error

Common causes

  1. Stage name in FROM ... AS starts with a digit (e.g., FROM node:18 AS 1-builder)
  2. Using version numbers as stage names (e.g., AS v2, AS 2.0)
  3. Stage names containing special symbols like @, #, $, or %
  4. Using build arguments that resolve to names starting with numbers
  5. Copying stage naming patterns from other tools that have different rules

How to fix "invalid stage name: stage name cannot start with a number"

1Identify the invalid stage name

Find the FROM instruction with the invalid stage name. Look for any stage name starting with a number:

Incorrect examples:

dockerfile
FROM node:18 AS 1builder
FROM golang:1.21 AS 2nd-stage
FROM python:3.11 AS 3build

Run the build with verbose output to see exactly which line fails:

bash
docker build --progress=plain -t myapp .

The error will indicate the problematic stage name in the message.

2Rename the stage with a letter prefix

Change the stage name to start with an alphabetic character. Use descriptive names that begin with letters:

Before (invalid):

dockerfile
FROM node:18 AS 1builder
WORKDIR /app
COPY package*.json ./
RUN npm install

After (valid):

dockerfile
FROM node:18 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install

If you need to indicate ordering, use words instead of numbers:

dockerfile
FROM node:18 AS stage-one
# or
FROM node:18 AS first-builder
3Update all references to the renamed stage

After renaming a stage, update all instructions that reference it:

dockerfile
# 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/html

Check for references in:
- FROM <stage> instructions
- COPY --from=<stage> instructions
- RUN --mount=type=bind,from=<stage> instructions

4Follow Docker stage naming conventions

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:

dockerfile
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 OK

Invalid examples:

dockerfile
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 hyphen
5Handle dynamic stage names with build arguments

If using ARG to create dynamic stage names, ensure the resolved value follows naming rules:

Problematic:

dockerfile
ARG VERSION=2
FROM node:18 AS ${VERSION}builder
# Resolves to "2builder" - invalid!

Fixed:

dockerfile
ARG VERSION=2
FROM node:18 AS builder-v${VERSION}
# Resolves to "builder-v2" - valid!

Or use a prefix:

dockerfile
ARG STAGE_NAME=stage1
FROM node:18 AS build-${STAGE_NAME}
6Use lowercase for BuildKit compatibility

While Docker allows uppercase stage names, BuildKit (the modern build engine) requires lowercase when referencing stages. For maximum compatibility, use lowercase:

dockerfile
# 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/html

The Docker documentation recommends lowercase stage names as a best practice.

Advanced notes

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:

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

dockerfile
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/html

However, 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.

Frequently asked questions

What does "invalid stage name: stage name cannot start with a number" mean?
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).
How do I fix "invalid stage name: stage name cannot start with a number"?
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.
What causes "invalid stage name: stage name cannot start with a number"?
Stage name in FROM ... AS starts with a digit (e.g., FROM node:18 AS 1-builder) Using version numbers as stage names (e.g., AS v2, AS 2.0) Stage names containing special symbols like @, #, $, or %
Is the "invalid stage name: stage name cannot start with a number" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading