...
Eroare Docker · Dockerfile și docker build

UndefinedVar: Usage of undefined variable '$VERSIUNE' (line 3)

Pe scurt

Build-ul folosește o variabilă care nu e declarată în etapa curentă, deci primește un text gol. Cel mai des, ARG e declarat înainte de FROM: redeclară-l după FROM (ARG VERSIUNE), ca valoarea să ajungă în etapă.

Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la

Ce înseamnă

UndefinedVar e o verificare a BuildKit (Docker 27+), afișată la final ca 1 warning found și apoi - UndefinedVar: Usage of undefined variable '$VERSIUNE' (line 3). Build-ul nu cade, dar $VERSIUNE e înlocuit cu nimic, deci imaginea iese greșit fără să observi.

Cauza clasică: un ARG declarat înainte de primul FROM e vizibil doar în liniile FROM. În interiorul etapei, ca să-l folosești în RUN, ENV sau COPY, trebuie redeclarat după FROM, doar cu numele (ARG VERSIUNE), iar atunci primește valoarea globală.

Alte cauze: greșeli de tastare ($VERSIUNEA față de ARG VERSIUNE), variabile definite în altă etapă a unui multi-stage (fiecare FROM începe de la zero) sau variabile de mediu de pe calculator, pe care build-ul nu le vede.

De ce apare: cauzele frecvente

1ARG global folosit în etapă

Greșit
BASH
ARG VERSIUNE=1.4
FROM node:20-alpine
RUN echo "Versiune: $VERSIUNE" > /versiune.txt
Corect
BASH
ARG VERSIUNE=1.4
FROM node:20-alpine
ARG VERSIUNE
RUN echo "Versiune: $VERSIUNE" > /versiune.txt

Redeclararea după FROM aduce valoarea globală în etapă.

2Nume scris diferit

Greșit
BASH
ARG PORT_APP=3000
ENV PORT=$PORT_API
Corect
BASH
ARG PORT_APP=3000
ENV PORT=$PORT_APP

Numele trebuie să fie identic, inclusiv literele mari și mici.

3Variabilă din altă etapă

Greșit
BASH
FROM node:20-alpine AS build
ARG MOD=productie
FROM nginx:1.27-alpine
RUN echo $MOD
Corect
BASH
FROM node:20-alpine AS build
ARG MOD=productie
FROM nginx:1.27-alpine
ARG MOD=productie
RUN echo $MOD

Fiecare etapă are propriile ARG; cele din etapa anterioară nu se moștenesc.

Repară tu

Repară eroarea, direct în pagină

În ~/versiune, build-ul imaginii versiune:1 avertizează UndefinedVar: Usage of undefined variable '$VERSIUNE' (line 3), iar /versiune.txt din imagine conține doar Versiune: . Repară Dockerfile-ul ca valoarea globală 1.4 să ajungă în etapă și reconstruiește versiune:1.

Indiciu

Adaugă ARG VERSIUNE imediat după FROM.

Alte forme ale mesajului

  • UndefinedVar: Usage of undefined variable '$NODE_ENV' (line 5)
  • UndefinedVar: Usage of undefined variable '$PORT' (did you mean $PORT_APP?) (line 4)

Cum o eviți pe viitor

Declară ARG chiar în etapa care îl folosește; dacă vrei aceeași valoare în mai multe etape, pune ARG NUME=valoare înainte de primul FROM și ARG NUME după fiecare FROM. Citește avertismentele de la finalul build-ului (docker build --check . le afișează fără să construiască) și verifică rezultatul cu docker run --rm imagine cat /fișier.

Întrebări frecvente

De ce build-ul nu dă eroare?

Pentru că o variabilă nedefinită e, în shell, doar un text gol. BuildKit te avertizează, dar construiește imaginea, ca să nu strice Dockerfile-uri vechi.

Pot face avertismentele erori?

Da, cu linia # check=error=true la începutul Dockerfile-ului: build-ul se oprește la orice avertisment de verificare.

Erori înrudite

← Toate erorile Docker

Tudor Andrei Dumitrescu
Cine a explicat eroarea

Tudor Andrei Dumitrescu

Senior Software Developer · fondatorul Academiei Programatorilor

LinkedIn
  1. 2019 Junior JavaCognizant Softvision
  2. 2021 Mid JavaCognizant Softvision
  3. 2022 Team LeaderEndava
  4. 2023 Senior Software DeveloperUniCredit
  5. Acum Senior Software DeveloperHCLTech
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu
Certificat de formator autorizatMinisterul Muncii și Ministerul Educației · 2022
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu

Certificat de formator autorizat · Ministerul Muncii și Ministerul Educației · 2022

Din 2020 construiește Academia Programatorilor, iar din 2026 și JoburiIT.ro. Fiecare eroare de aici a fost reprodusă în editorul nostru: codul greșit chiar dă mesajul din titlu, iar reparația chiar funcționează.

Învață Docker de la zero, cu exerciții la fiecare lecție

Curs Docker: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 15 lecții sunt gratuite.