Improve error message for invalid virtualenvs.prompt config

[aryanyk]

Pull Request Check List

Resolves: #Resolves: #10635

Summary

Improve error message when an invalid template variable is used in virtualenvs.prompt configuration.

Details

Previously an invalid placeholder such as {python-version} resulted in a cryptic KeyError. This change catches the error and raises a clearer PoetryError explaining the config source and how to fix it.

Testing

• Reproduced and validated locally using WSL (Ubuntu)

Summary by Sourcery

Bug Fixes:

• Prevent cryptic KeyError when virtualenv prompt configuration contains an unknown template variable by raising a descriptive PoetryError instead.

[sourcery-ai[bot]]

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

Improves handling of invalid template variables in the virtualenv prompt configuration by converting a raw KeyError into a clearer, user-facing PoetryError with guidance on how to fix the configuration.

Sequence diagram for handling invalid virtualenvs.prompt template variables

sequenceDiagram
    actor User
    participant PoetryCLI
    participant EnvManager
    participant PythonFormatEngine

    User->>PoetryCLI: Run_command_that_creates_virtualenv
    PoetryCLI->>EnvManager: create_venv(venv_prompt)

    alt venv_prompt_is_not_none
        EnvManager->>PythonFormatEngine: venv_prompt.format(project_name, python_version)
        alt template_variable_is_valid
            PythonFormatEngine-->>EnvManager: formatted_prompt
            EnvManager-->>PoetryCLI: virtualenv_created_with_custom_prompt
            PoetryCLI-->>User: Command_succeeds
        else template_variable_is_invalid
            PythonFormatEngine-->>EnvManager: KeyError
            EnvManager-->>PoetryCLI: PoetryError_invalid_template_variable
            PoetryCLI-->>User: Clear_error_message_with_config_guidance
        end
    else venv_prompt_is_none
        EnvManager-->>PoetryCLI: virtualenv_created_with_default_prompt
        PoetryCLI-->>User: Command_succeeds
    end

File-Level Changes

Change	Details	Files
Add defensive error handling around virtualenv prompt formatting to surface clearer configuration errors to users.	Wrap the venv_prompt.format(...) call in a try/except block to intercept KeyError caused by unknown template variables. On KeyError, raise a PoetryError instead of letting the KeyError propagate, preserving the original exception as the cause. Include the invalid template variable name and the configuration option path (virtualenvs.prompt) in the PoetryError message, with guidance to check the Poetry configuration file.	src/poetry/utils/env/env_manager.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
https://github.com/python-poetry/poetry/issues/10635	Provide a clear and descriptive error message when an invalid template variable is used in the virtualenvs.prompt configuration (e.g., {python-version} instead of {python_version}).	✅
https://github.com/python-poetry/poetry/issues/10635	Ensure the error message indicates that the problem originates from the global Poetry configuration (virtualenvs.prompt), not from Python or the local pyproject.toml.	✅

Possibly linked issues

• #10635: PR catches KeyError from invalid virtualenvs.prompt and raises a clear PoetryError, matching the issue’s request.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an issue from a review comment by replying to it. You can also reply to a review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull request title to generate a title at any time. You can also comment @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in the pull request body to generate a PR summary at any time exactly where you want it. You can also comment @sourcery-ai summary on the pull request to (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the pull request to resolve all Sourcery comments. Useful if you've already addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull request to dismiss all existing Sourcery reviews. Especially useful if you want to start fresh with a new review - don't forget to comment @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[aryanyk]

Thanks for the feedback! Makes sense — I’ll update the error message to include the supported template variables and reference the concrete config source so it’s easier for users to fix. Will push an update shortly.

[aryanyk]

I’ve updated the error message to include the supported template variables and more concrete config hints, and applied Ruff formatting. Let me know if you’d like the wording tweaked further.

[aryanyk]

Hi @radoering ,

I’ve pushed the requested changes and all CI checks are green now ✅
Could you please review the PR when you get a chance?

Thanks for your time and guidance!