What causes "failed to get subprocesses" in benfred/py-spy?

Retry promptly after confirming the target process is still alive (the target may have exited mid-scan).

failed to get subprocesses

Error message

failed to get subprocesses

What it means

With --subprocesses, py-spy enumerates the target's child processes via process.process.child_processes() in DumpData::write_traces. If the OS API for enumerating child processes fails, expect() panics with "failed to get subprocesses" instead of continuing with just the parent trace.

Source

Thrown at src/dump.rs:68

            out,
            "Parent Process {}: {}",
            style(parentpid).bold().yellow(),
            parentprocess.cmdline()?.join(" ")
        )?;
    }
    writeln!(out)?;
    let traces = process
        .get_stack_traces()
        .context("Failed to get stack traces")?;
    for trace in traces.iter().rev() {
        write_trace(out, trace, true)?;
    }

    if config.subprocesses {
        for (childpid, parentpid) in process
            .process
            .child_processes()
            .expect("failed to get subprocesses")
        {
            let term = Term::stdout();
            let (_, width) = term.size();

            writeln!(out, "\n{}", &style("-".repeat(width as usize)).dim())?;
            // child_processes() returns the whole process tree, since we're recursing here
            // though we could end up printing grandchild processes multiple times. Limit down
            // to just once
            if parentpid == pid {
                write_traces(out, childpid, config, Some(parentpid))?;
            }
        }
    }
    Ok(())
}

#[cfg(target_os = "linux")]
pub fn print_trace(trace: &StackTrace, include_activity: bool) {

View on GitHub (pinned to 32080cc0c2)

Solutions

Retry promptly after confirming the target process is still alive (the target may have exited mid-scan).
Run py-spy with elevated privileges (sudo on Linux/macOS, Administrator on Windows) so child process metadata is readable.
Drop --subprocesses and profile each pid individually if the process tree is unstable.
Profile the child directly instead of the parent when you know which worker you care about.

Example fix

// before
py-spy record --pid 1234 --subprocesses  # target died mid-scan: panic
// after
ps -p 1234 && py-spy record --pid 1234 --subprocesses  # verify alive first; sudo if needed
sudo py-spy record --pid 1234 --subprocesses

Defensive patterns

Strategy: retry

Validate before calling

kill -0 "$PID" 2>/dev/null || { echo "target $PID already exited" >&2; exit 1; }

Try / catch

run py-spy; if it aborts with 'failed to get subprocesses', verify the target is alive and retry with elevated privileges:
for i in 1 2 3; do
  sudo py-spy dump --pid "$PID" --subprocesses && break
  sleep 1
done

Prevention

Confirm the target survives the scan window before using --subprocesses.
Run py-spy with sudo/Administrator when profiling other users' processes.
Profile individual child pids instead of the tree when children churn rapidly.

When it happens

Trigger: Running `py-spy dump --pid <pid> --subprocesses` (or record with --subprocesses) when the child_processes() syscall fails — e.g. the target exited between opening it and enumeration, permission denied reading /proc entries, or a Windows API failure enumerating process tree.

Common situations: Profiling a short-lived parent that respawns/exits children rapidly, profiling processes owned by another user without elevated privileges, or containers where /proc child listings are restricted.

Related errors

failed to get subprocesses

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