plandex-ai/plandex · critical

LiteLLM proxy launch failed: %w

Error message

LiteLLM proxy launch failed: %w

What it means

The library failed to launch the local LiteLLM proxy server process. startLiteLLMServer returned an error during startup (within a 10s window), logged and wrapped here as finalErr. Any code depending on the proxy for model routing will be unavailable.

Source

Thrown at app/server/model/litellm.go:36

)

func EnsureLiteLLM(numWorkers int) error {
	var finalErr error
	liteLLMOnce.Do(func() {
		if isLiteLLMHealthy() {
			log.Println("LiteLLM proxy is already healthy")
			return
		}

		log.Println("LiteLLM proxy is not running. Starting...")

		ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
		defer cancel()

		err := startLiteLLMServer(numWorkers)
		if err != nil {
			log.Println("LiteLLM proxy launch failed:", err)
			finalErr = fmt.Errorf("LiteLLM proxy launch failed: %w", err)
			return
		}

		ticker := time.NewTicker(500 * time.Millisecond)
		defer ticker.Stop()

		for {
			select {
			case <-ctx.Done():
				log.Println("LiteLLM proxy launch timed out")
				finalErr = fmt.Errorf("LiteLLM proxy launch timed out")
				return
			case <-ticker.C:
				if isLiteLLMHealthy() {
					log.Println("LiteLLM proxy is healthy")
					return
				} else {
					log.Println("LiteLLM proxy is not healthy yet, retrying after 500ms...")

View on GitHub (pinned to e2d772072e)

Solutions

1. Read the wrapped cause in logs for the exact spawn failure
2. Verify litellm is installed and on PATH (`litellm --version` or `pip show litellm`)
3. Check that the proxy port is free (lsof/netstat) and not bound by a stale process
4. Validate the litellm config file referenced by the launcher
5. Ensure deployment image includes Python and LiteLLM dependencies

Example fix

// before: silent dependency on litellm being installed
err := startLiteLLMServer(numWorkers)
// after: preflight the binary
if _, err := exec.LookPath("litellm"); err != nil {
    return fmt.Errorf("litellm not installed: %w", err)
}
err := startLiteLLMServer(numWorkers)

if _, err := exec.LookPath("litellm"); err != nil {
    return fmt.Errorf("litellm not installed or not on PATH")
}
if cfg == nil || cfg.ConfigPath == "" { return errors.New("litellm config path missing") }

err := EnsureLiteLLMRunning(numWorkers)
if err != nil {
    var launchErr *LaunchError
    if errors.As(err, &launchErr) { log.Fatalf("litellm launch: %v", launchErr.Cause) }
    return err
}

When it happens

Trigger: startLiteLLMServer(numWorkers) fails: litellm binary/Python module missing, port already in use, invalid litellm config file, insufficient permissions, or the process exits immediately after spawn.

Common situations: LiteLLM not installed or wrong Python environment; config.yaml path/env vars missing; port conflict with another process; host missing python/pip or venv not activated in deployment image.

Related errors

• LiteLLM proxy launch timed out
• error checking settings: %v
• failed to signal LiteLLM for shutdown: %w
• Error getting active model stream
• No active model stream for plan

AI-assisted analysis of plandex-ai/plandex@e2d772072e (2026-09-05). Data as JSON: /api/errors/b002aacab4fcc926. Report an issue: GitHub.