python-poetry/poetry · error · PoetryConsoleError

Invalid template variable '{e.args[0]}' in 'virtualenvs.prom

Error message

Invalid template variable '{e.args[0]}' in 'virtualenvs.prompt' setting.
Valid variables are: {{project_name}}, {{python_version}}

What it means

Raised as PoetryConsoleError in EnvManager.create_venv when formatting the virtualenvs.prompt config value raises a KeyError - i.e. the template string references a placeholder other than the two supported ones ({project_name} and {python_version}). Only those two variables are provided to str.format.

Source

Thrown at src/poetry/utils/env/env_manager.py:454

            )

            python = Python.get_compatible_python(poetry=self._poetry, io=self._io)

        if in_project_venv:
            venv = venv_path
        else:
            name = self.generate_env_name(name, str(cwd))
            name = f"{name}-py{python.minor_version.to_string()}"
            venv = venv_path / name

        if venv_prompt is not None:
            try:
                venv_prompt = venv_prompt.format(
                    project_name=self._poetry.package.name or "virtualenv",
                    python_version=python.minor_version.to_string(),
                )
            except KeyError as e:
                raise PoetryConsoleError(
                    f"Invalid template variable '{e.args[0]}' in 'virtualenvs.prompt' setting.\n"
                    f"Valid variables are: {{project_name}}, {{python_version}}"
                ) from e
            except ValueError as e:
                raise PoetryConsoleError(
                    f"Invalid template string in 'virtualenvs.prompt' setting: {e}"
                ) from e

        if not venv.is_dir():
            if create_venv is False:
                self._io.write_error_line(
                    "<fg=black;bg=yellow>"
                    "Skipping virtualenv creation, "
                    "as specified in config file."
                    "</>"
                )

                return self.get_system_env()

View on GitHub (pinned to 92b74dcfe3)

Solutions

  1. Use only the supported placeholders: {project_name} and {python_version}.
  2. Reconfigure: 'poetry config virtualenvs.prompt "{project_name}-py{python_version}"'.
  3. Reset to default: 'poetry config --unset virtualenvs.prompt'.
  4. Check for stray braces that should be literal - escape them as {{ }}.

Example fix

// before
poetry config virtualenvs.prompt "{name}-{py}"
# create_venv -> KeyError -> PoetryConsoleError

// after
poetry config virtualenvs.prompt "{project_name}-{python_version}"
Defensive patterns

Strategy: validation

Validate before calling

import re

ALLOWED = {"project_name", "python_version"}

def prompt_template_ok(tpl: str) -> bool:
    for m in re.finditer(r"\{([a-zA-Z_][a-zA-Z0-9_]*)\}", tpl):
        if m.group(1) not in ALLOWED:
            return False
    return True

# before setting config:
assert prompt_template_ok(new_prompt), "unsupported placeholder"

Type guard

from poetry.console.exceptions import PoetryConsoleError

def is_invalid_prompt_variable(e: Exception) -> bool:
    return isinstance(e, PoetryConsoleError) and "Invalid template variable" in str(e)

Try / catch

from poetry.console.exceptions import PoetryConsoleError

try:
    manager.create_venv()
except PoetryConsoleError as e:
    if "Invalid template variable" in str(e):
        # reset the misconfigured prompt and retry
        run_cli(["poetry", "config", "--unset", "virtualenvs.prompt"])
        manager.create_venv()
    else:
        raise

Prevention

When it happens

Trigger: Configuring 'virtualenvs.prompt' with a template like "{name}-env" or "{py_version}" (unsupported placeholder) via 'poetry config virtualenvs.prompt "{name}"', then triggering venv creation. KeyError caught at env_manager.py:448-457.

Common situations: User invents a placeholder name; copy-pastes a prompt template from another tool (e.g. starship) that uses different tokens; uses snake_case variants like {pythonVersion}.

Related errors

AI-assisted analysis of python-poetry/poetry@92b74dcfe3 (2026-08-04). Data as JSON: /data/errors/bfedecbf661f92e3.json. Report an issue: GitHub.