Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Vite environment variables are undefined inside a Docker container

Errorimport.meta.env.VITE_API_URL is undefined

Short answer

Vite replaces import.meta.env values while it builds, not when the container starts. A variable given only at runtime (docker run -e or Compose environment) comes too late. Name it with the VITE_ prefix, declare it as ARG and ENV before the build command, and pass it with --build-arg.

  • Applies to Vite 6 and 7, Docker Engine 27 and 28, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check whether the value was baked into the built files. If the string is missing from dist, the build never saw the variable.

    docker run --rm my-app-image sh -c 'grep -rl "https://api.example.com" /usr/share/nginx/html | head'
  2. 2Match what you see, then jump to its fix

    1. 1The variable shows in docker exec my-app env, yet the page still reads undefinedThe variable is set at runtime, but Vite needed it at build timeFix
    2. 2Only variables named without the prefix read as undefined in client codeThe variable name has no VITE_ prefixFix
    3. 3The ARG line exists, but the build still sees an empty value in a multi-stage DockerfileThe ARG is declared in the wrong build stageFix

What does the error look like?

  • import.meta.env.VITE_API_URL is undefined
  • VITE_ variable shows undefined in the browser console

Cause 1 of 3

The variable is set at runtime, but Vite needed it at build time

1Check

Vite statically replaces import.meta.env at build time. A container started with -e or a Compose environment block only changes the running container, after the files were already built.

docker exec my-app env | grep VITE_
grep -n "npm run build" Dockerfile

2Fix

Make the value available to the build step. Docker's build arguments are not in the container by default, so turn the argument into an environment variable inside the build stage, before npm run build.

# Dockerfile
FROM node:22 AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
ARG VITE_API_URL
ENV VITE_API_URL=$VITE_API_URL
RUN npm run build

# build command
docker build --build-arg VITE_API_URL=https://api.example.com -t my-app-image .

3Verify

The built files contain the value.

docker run --rm my-app-image sh -c 'grep -rl "https://api.example.com" /usr/share/nginx/html | head'

Confirmed by vite.dev

Did this fix it?

Cause 2 of 3

The variable name has no VITE_ prefix

1Check

Vite includes only prefixed variables in client code; others, such as DB_PASSWORD, read as undefined there. The prefix can be changed with the envPrefix option.

grep -rn "import.meta.env" src | head
grep -n "envPrefix" vite.config.*

2Fix

Rename the variable to start with VITE_ (or set envPrefix on purpose) and update the Dockerfile and build command to match. Never put secrets in a VITE_ variable: it is readable by anyone who loads the site.

ARG VITE_API_URL
ENV VITE_API_URL=$VITE_API_URL

3Verify

Rebuild the image and read the value in the browser console.

docker build --build-arg VITE_API_URL=https://api.example.com -t my-app-image .

Confirmed by vite.dev

Did this fix it?

Cause 3 of 3

The ARG is declared in the wrong build stage

1Check

Docker does not pass a global ARG (declared before FROM) into build stages. Inside the stage, you have to repeat ARG NAME.

grep -n -E '^(ARG|FROM|ENV)' Dockerfile

2Fix

Declare ARG inside the stage that runs npm run build, then ENV, in that order, before the build command.

ARG VITE_API_URL
FROM node:22 AS build
ARG VITE_API_URL
ENV VITE_API_URL=$VITE_API_URL
RUN npm run build

3Verify

Build with the argument and check the output files for the value.

docker build --no-cache --build-arg VITE_API_URL=https://api.example.com -t my-app-image .

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Treat every VITE_ value as public: it is bundled into the client code.
  • Build one image per environment, or load runtime settings from a config file your app fetches when it starts.
  • With Docker Compose, put the value under build.args, not only under environment.
  • Vite gives variables already set in the shell priority over .env files, so build-stage ENV values win.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.