UndefinedVar: Usage of undefined variable '$VERSIUNE' (line 3)
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ă
ARG VERSIUNE=1.4
FROM node:20-alpine
RUN echo "Versiune: $VERSIUNE" > /versiune.txtARG VERSIUNE=1.4
FROM node:20-alpine
ARG VERSIUNE
RUN echo "Versiune: $VERSIUNE" > /versiune.txtRedeclararea după FROM aduce valoarea globală în etapă.
2Nume scris diferit
ARG PORT_APP=3000
ENV PORT=$PORT_APIARG PORT_APP=3000
ENV PORT=$PORT_APPNumele trebuie să fie identic, inclusiv literele mari și mici.
3Variabilă din altă etapă
FROM node:20-alpine AS build
ARG MOD=productie
FROM nginx:1.27-alpine
RUN echo $MODFROM node:20-alpine AS build
ARG MOD=productie
FROM nginx:1.27-alpine
ARG MOD=productie
RUN echo $MODFiecare etapă are propriile ARG; cele din etapa anterioară nu se moștenesc.
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.
Reparația
ARG VERSIUNE=1.4
FROM node:20-alpine
ARG VERSIUNE
RUN echo "Versiune: $VERSIUNE" > /versiune.txt
CMD ["cat", "/versiune.txt"]docker build -t versiune:1 .
docker run --rm versiune:1Versiune: 1.4De ce merge
ARG VERSIUNE=1.4 era declarat înainte de FROM, unde e vizibil doar pentru liniile FROM. În etapă, $VERSIUNE era gol. ARG VERSIUNE după FROM aduce variabila în etapă cu valoarea globală, deci RUN echo scrie Versiune: 1.4, iar avertismentul dispare.
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
ERROR: failed to solve: base name (${BASE_IMAGE}) should not be blank FROM folosește o variabilă ARG care, la momentul build-ului, e goală: ARG-ul n-are valoare implicită și n-ai dat --build-arg, sau ARG-ul e declarat după FROM. Pune ARG BASE_IMAGE=node:20-alpine înainte de primul FROM sau rulează docker build --build-arg BASE_IMAGE=node:20-alpine. LegacyKeyValueFormat: "ENV key=value" should be used instead of legacy "ENV key value" format (line 3) Avertismentul build-ului spune că ai scris ENV PORT 3000 (forma veche, cu spațiu). Folosește forma cu egal: ENV PORT=3000 (și la fel la LABEL și ARG), care permite și mai multe variabile pe aceeași linie fără ambiguitate. JSONArgsRecommended: JSON arguments recommended for CMD to prevent unintended behavior related to OS signals (line 5) Avertismentul build-ului spune că CMD (sau ENTRYPOINT) e scris în forma shell, deci procesul principal devine /bin/sh și aplicația nu primește SIGTERM la docker stop. Scrie-l în forma exec, ca listă JSON: CMD ["node", "server.js"]. Î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.
