Missing environment variable doesn't throw an error in Tox 4+

[plondino]

Issue

Per the documentation, a missing environment variable should throw an error: https://tox.wiki/en/latest/config.html#environment-variable-substitutions. However, this doesn't seem to the be the case in tox 4+ - the value is just retrieved as an empty string.

Environment

Provide at least:

• OS: macOS Sonoma 14.7.1

Output of pip list of the host Python, where tox is installed

Package       Version
------------- -------
cachetools    5.5.0
chardet       5.2.0
colorama      0.4.6
distlib       0.3.9
filelock      3.16.1
packaging     24.2
pip           24.3.1
platformdirs  4.3.6
pluggy        1.5.0
py            1.11.0
pyproject-api 1.8.0
six           1.17.0
tox           4.0.0
virtualenv    20.28.0

Output of running tox

Output of tox -rvv

In 3.x:

ERROR:   python: unresolvable substitution(s):
    commands: 'FOO'
Environment variables are missing or defined recursively.

In 4.x:

Python 3.12.5
py: commands[1]> echo bar
bar
py: commands[2]> echo

Minimal example

Where neither variable is defined:

[tox]
skipsdist = true

[testenv]
allowlist_externals =
    echo
setenv =
    TEST_ENVIRONMENT={env:FOO}

commands =
    python --version
    echo {env:FOO:bar}
    echo {env:TEST_ENVIRONMENT:baz}

Not sure if this is intended but at least the documentation should be updated - if it's intended, then is there any way to mark a variable as required?

[jugmac00]

@gaborbernat What's your take on this? I am happy to either update the documentation or look into a fix.

[gaborbernat]

I think we should update the documentation.