benfred/py-spy · error

invalid pid

Error message

invalid pid

What it means

The --pid option is parsed in Config::from_args. If the value has a "0x" prefix it is parsed as hexadecimal with Pid::from_str_radix, otherwise as decimal; either failure panics with "invalid pid" because the string is not a valid process id.

Source

Thrown at src/config.rs:455

        match subcommand {
            "record" | "top" => {
                config.python_program = matches
                    .get_many::<String>("python_program")
                    .map(|vals| vals.map(|v| v.to_owned()).collect());
                config.gil_only = matches.get_flag("gil");
                config.include_idle = matches.get_flag("idle");
            }
            _ => {}
        }

        config.subprocesses = matches.get_flag("subprocesses");
        config.command = subcommand.to_owned();

        // options that can be shared between subcommands
        config.pid = matches.get_one::<String>("pid").map(|p| {
            // allow pid to be specified as a hexadecimal value
            match p.to_lowercase().strip_prefix("0x") {
                Some(prefix) => Pid::from_str_radix(prefix, 16).expect("invalid pid"),
                None => p.parse().expect("invalid pid"),
            }
        });

        config.full_filenames = matches.get_flag("full_filenames");
        if cfg!(feature = "unwind") {
            config.native = matches.get_flag("native");
        }

        config.capture_output = config.command != "record" || matches.get_flag("capture");
        if !config.capture_output {
            config.hide_progress = true;
        }

        if matches.get_flag("nonblocking") {
            // disable native profiling if invalidly asked for
            if config.native {
                eprintln!("Can't get native stack traces with the --nonblocking option.");

View on GitHub (pinned to 32080cc0c2)

Solutions

  1. Pass the pid as a plain decimal number from `ps`/Task Manager, e.g. `py-spy dump --pid 1234`.
  2. If the pid is hexadecimal, keep the 0x prefix: `py-spy dump --pid 0x4d2` (equivalent to 1234).
  3. On Windows, verify Task Manager's Details tab PID (decimal); beware tools that report hex pids.
  4. Sanitize/validate the pid variable in shell scripts before invoking py-spy.

Example fix

// before: hex pid without prefix
py-spy dump --pid 1a2b   # panic: invalid pid
// after
py-spy dump --pid 0x1a2b  # or decimal 6699
Defensive patterns

Strategy: validation

Validate before calling

case "$PID" in
  0x*) : ;;
  ''|*[!0-9]*) echo "--pid must be decimal (or 0x hex)" >&2; exit 1 ;;
esac

Prevention

When it happens

Trigger: Running any py-spy subcommand with `--pid <value>` where value is not a decimal number (and, with the 0x prefix, not valid hex) — e.g. `--pid 12a4` without 0x, `--pid 0xZZ`, `--pid ""`, or a negative number like `--pid -1`.

Common situations: Copy-pasting a pid that includes surrounding text, accidentally omitting the 0x prefix on a hex pid (Windows Device Manager / tools that show hex pids), or passing a variable that is empty in a script.

Related errors

AI-assisted analysis of benfred/py-spy@32080cc0c2 (2026-09-05). Data as JSON: /api/errors/e033d8bea89aceb8. Report an issue: GitHub.