Python Environments "Unable to handle /usr/share/jupyter/kernels/pythonEnv/helper"

[Yuekai-Song]

I encounter the following error from Python Environments every time I open VS Code:

and here is theOUTPUT from Python Environments

2026-02-26 08:44:44.056 [error] [pet] �[2m  13.322186468s�[0m �[31mERROR�[0m �[2mpet_python_utils::env�[0m�[2m:�[0m Python Execution for “/usr/share/jupyter/kernels/pythonEnv/helper” produced an output “” without a separator
�[2m  13.322206879s�[0m �[33m WARN�[0m �[2mpet::resolve�[0m �[2m:�[0m Unknown Python Env “/usr/share/jupyter/kernels/pythonEnv/helper”
�[2m  13.322217845s�[0m �[31mERROR�[0m �[2mpet::jsonrpc�[0m �[2m:�[0m Failed to resolve env “/usr/share/jupyter/kernels/pythonEnv/helper”

2026-02-26 08:44:44.056 [error] Unable to handle /usr/share/jupyter/kernels/pythonEnv/helper

The error appears immediately on startup, even when no notebook is opened.

---

Kernel Files

/usr/share/jupyter/kernels/pythonEnv/helper

#! /bin/bash -il

exec "$@"

/usr/share/jupyter/kernels/pythonEnv/kernel.json

{
  "display_name": "Python ENV",
  "language": "python",
  "argv": [
    "/usr/share/jupyter/kernels/pythonEnv/helper",
    "python",
    "-m",
    "ipykernel_launcher",
    "-f",
    "{connection_file}"
  ]
}

Environment

• OS: AlmaLinux 9
• Python Environments extension version: 1.20.1

If I switch to Python Environments 1.16 (last release), the same error also occurs, but it only appears in theOUTPUT. There is no intrusive notification like the one shown in the screenshot above for 1.20.1.

[karthiknadig]

Root Cause Analysis

Traced the full error flow from the extension through PET. Here's what's happening:

Error Flow

External caller (likely Jupyter extension)
  → api.resolveEnvironment(Uri.file("/usr/share/jupyter/kernels/pythonEnv/helper"))
    → pythonApi.resolveEnvironment()                         [pythonApi.ts]
      → handlePythonPath(uri, managers, projectManagers)     [pythonPath.ts]
        → iterates ALL managers calling manager.resolve(uri)
          → sysPythonManager.resolve()
            → resolveSystemPythonEnvironmentPath()           [utils.ts]
              → nativeFinder.resolve(fsPath)
                → PET JSONRPC "resolve" request
                  → Spawns: "/usr/share/jupyter/kernels/pythonEnv/helper" -c "import sys;..."
                  → Output is "" → ERROR logged → JSONRPC error -4
              → throws → resolveSystemPythonEnvironmentPath returns undefined
          → ALL managers return undefined
        → showErrorMessage("Unable to handle ...")           ← INTRUSIVE NOTIFICATION

Two Issues on This Side

1. handlePythonPath shows intrusive error notification for programmatic API calls

In src/common/utils/pythonPath.ts lines 77-78:

traceError(`Unable to handle ${interpreterUri.fsPath}`);
showErrorMessage(`Unable to handle ${interpreterUri.fsPath}`);

When no manager can resolve a URI, handlePythonPath unconditionally calls showErrorMessage(). This is too aggressive — the resolveEnvironment API returning undefined is the correct contract for unresolvable paths. The notification should only appear for user-initiated actions (browse for interpreter, enter path), not programmatic API calls from other extensions.

2. No path validation before sending to PET resolve

In src/managers/builtin/utils.ts (resolveSystemPythonEnvironmentPath), any path is sent directly to PET's resolve endpoint without checking if it could plausibly be a Python executable. PET then spawns the path as a process, wasting time (~13 seconds in this case). In venvUtils.ts, a failing resolve even hits PET twice (once for venv, then falls through to system resolve).

What Didn't Change

The handlePythonPath, resolveEnvironment, and sysPythonManager.resolve code are all identical between v1.16 and HEAD. The showErrorMessage call has existed since the first commit. The difference the user observes (notification in v1.20.1 but not v1.16) is likely due to the calling extension (Jupyter) recently starting to call resolveEnvironment() with kernel spec argv[0] paths.

PET-Side Issue

Filed separately: https://github.com/microsoft/python-environment-tools/issues/TBD — PET should validate that the filename looks like a Python executable before spawning it in resolve_environment().

Suggested Fixes

1. Remove showErrorMessage from handlePythonPath — or gate it so it only shows for user-initiated actions, not programmatic resolveEnvironment() API calls.
2. Add basic filename validation before calling nativeFinder.resolve() — check if the path looks like a Python executable.
3. PET-side — validate executable filename before spawning (separate issue).

[karthiknadig]

PET-side issue created: microsoft/python-environment-tools#364