anomalyco/sst · error

failed to start worker process: %v

Error message

failed to start worker process: %v

What it means

Raised in PythonRuntime.Run (pkg/runtime/python/python.go:210) when cmd.Start() fails to launch `uv run lambdaric_python_bridge.py <handler>`. This is the most common of the three worker-spawn errors: the `uv` binary is missing, the bridge script does not exist, the working directory is invalid, or the executable is not found. The dev server cannot start the Python Lambda worker at all.

Source

Thrown at pkg/runtime/python/python.go:210

		env = append(env, "PYTHONPATH="+pythonPath)

		resourceEncPath := filepath.Join(input.Build.Out, "resource.enc")
		env = append(env, "SST_KEY_FILE="+resourceEncPath)
	}

	cmd.Env = env
	cmd.Dir = workingDir
	stdout, err := cmd.StdoutPipe()
	if err != nil {
		return nil, fmt.Errorf("failed to create stdout pipe: %v", err)
	}
	stderr, err := cmd.StderrPipe()
	if err != nil {
		return nil, fmt.Errorf("failed to create stderr pipe: %v", err)
	}

	if err := cmd.Start(); err != nil {
		return nil, fmt.Errorf("failed to start worker process: %v", err)
	}

	return &worker{
		stdout,
		stderr,
		cmd,
	}, nil

}

func (r *PythonRuntime) ShouldRebuild(functionID string, file string) bool {
	// Skip paths inside build artifacts, caches, or virtual envs to avoid feedback loops
	normalized := filepath.ToSlash(file)
	for _, dir := range []string{".sst", ".venv", "venv", "__pycache__", ".git", "node_modules", ".pytest_cache", ".mypy_cache", ".tox"} {
		if strings.Contains(normalized, dir+"/") {
			return false
		}
	}

View on GitHub (pinned to a0bd20f762)

Solutions

1. Install uv and verify it is resolvable: `which uv` from the same shell/user that runs sst dev; if missing run `curl -LsSf https://astral.sh/uv/install.sh | sh`
2. Confirm the platform bridge exists: check .sst/platform/dist/python-runtime/index.py; re-run `bun run build:platform` or reinstall the platform files if absent
3. Verify the artifact/working directory exists and the handler resolves; redeploy or restart `sst dev` to resync artifacts
4. Check the wrapped error text: 'executable file not found in $PATH' means fix PATH; 'no such file or directory' naming the bridge means fix bridge copy

Example fix

// before (shell where sst runs lacks uv)
$ sst dev  -> failed to start worker process: exec: "uv": executable file not found in $PATH
// after
$ curl -LsSf https://astral.sh/uv/install.sh | sh
$ which uv && sst dev

// preflight before sst dev
if _, err := exec.LookPath("uv"); err != nil {
    panic("uv not installed: curl -LsSf https://astral.sh/uv/install.sh | sh")
}
if _, err := os.Stat(filepath.Join(platformDir, "dist/python-runtime/index.py")); err != nil {
    panic("platform python bridge missing: rebuild platform")
}

w, err := rt.Run(ctx, input)
if err != nil {
    var ee *exec.Error
    if errors.As(err, &ee) || strings.Contains(err.Error(), "executable file not found") {
        // install/repair uv and retry once
        installUv(); return rt.Run(ctx, input)
    }
    return err
}

When it happens

Trigger: `uv` not installed or not on PATH; lambdaBridgePath missing (platform dist/python-runtime/index.py absent or copy failed silently); workingDir (artifact dir or project root) deleted; env malformed; handler file path invalid causing uv to exit immediately (uv run errors surface here as start failures only if exec itself fails — usually missing binary).

Common situations: Fresh machine without uv (macOS/Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh` not run); PATH differing inside the sst dev process vs shell; project root renamed while dev session running; Windows without WSL where uv resolution differs.

Related errors

• uv pip install timed out after 15 minutes - check network co
• failed to run uv pip install: %v %s Function: %s Handler: %
• uv build failed: %w
• uv build failed (exit code %d): %s
• UV export failed: %w

AI-assisted analysis of anomalyco/sst@a0bd20f762 (2026-08-30). Data as JSON: /api/errors/dc58988739ed1eb3. Report an issue: GitHub.