pola-rs/polars · error · RuntimeError

launch.py is not meant to be executed directly; please use…

Error message

launch.py is not meant to be executed directly; please use the `Python: Debug Rust` debugging configuration to run a python script that uses the polars library.

What it means

py-polars/debug/launch.py is a helper that lets VSCode attach an LLDB debugger to a Python process running polars. Running it directly (no script argument) raises this RuntimeError telling you to use the 'Python: Debug Rust' launch configuration instead.

Solutions

Use the 'Python: Debug Rust' configuration in VSCode (F5) with your target python script, not `python launch.py` directly
Run the debug flow as described in the contributing guide: https://docs.pola.rs/development/contributing/ide/#debugging
If invoking programmatically, pass the python script to debug as an argument so len(sys.argv) > 1

Example fix

// before
python py-polars/debug/launch.py
// after
# In VSCode: select 'Python: Debug Rust' configuration and press F5 with your script
python py-polars/debug/launch.py my_script.py  # only if you must invoke manually

Defensive patterns

Strategy: type-guard

Validate before calling

import sys
if len(sys.argv) == 1:
    raise SystemExit("Use the 'Python: Debug Rust' VSCode configuration instead of running launch.py directly")

Try / catch

try:
    import launch  # or execfile
except RuntimeError as e:
    print(f'Debug helper misuse: {e}. Use the Python: Debug Rust configuration.')

Prevention

Always start polars Rust debugging via the VSCode 'Python: Debug Rust' configuration
Never invoke launch.py manually from the shell
Keep the contributing guide's debugging setup documented for the team

When it happens

Trigger: Executing `python launch.py` (or the debugpy adapter invoking it) without a target script in sys.argv.

Common situations: Running the file manually from a terminal to 'test' debugging; a misconfigured .vscode/launch.json that invokes launch.py without the 'module'/'args' pointing at a user script.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

AI-assisted analysis of pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/6b8c51374d46440f. Report an issue: GitHub.

Appendix: source

Thrown at py-polars/debug/launch.py:29

consistently, it is recommended to increase this value.
"""
LLDB_DEBUG_WAIT_TIME_SECONDS = 1


def launch_debugging() -> None:
    """
    Debug Rust files via Python.

    Determine the pID for the current debugging session, attach the Rust LLDB launcher,
    and execute the originally-requested script.
    """
    if len(sys.argv) == 1:
        msg = (
            "launch.py is not meant to be executed directly; please use the `Python: "
            "Debug Rust` debugging configuration to run a python script that uses the "
            "polars library."
        )
        raise RuntimeError(msg)

    # Get the current process ID.
    pID = os.getpid()

    # Print to the debug console to allow VSCode to pick up on the signal and start the
    # Rust LLDB configuration automatically.
    launch_file = Path(__file__).parents[2] / ".vscode/launch.json"
    if not launch_file.exists():
        msg = f"Cannot locate {launch_file}"
        raise RuntimeError(msg)
    with launch_file.open("r") as f:
        launch_info = f.read()

    # Overwrite the pid found in launch.json with the pid for the current process.
    # Match the initial "Rust LLDB" definition with the pid defined immediately after.
    pattern = re.compile('("Rust LLDB",\\s*"pid":\\s*")\\d+(")')
    found = pattern.search(launch_info)
    if not found:

View on GitHub (pinned to fe841f959e)