What causes "failed to initialize lsp client: %w" in charmbracelet/crush?

Run the server binary manually with the same args and cwd to see its startup errors.

failed to initialize lsp client: %w

Error message

failed to initialize lsp client: %w

What it means

Client.Restart re-registers handlers and calls c.client.Initialize to perform the LSP initialize handshake. If the initialize request fails (or errors during the exchange), the client transitions to StateError and this wrapped error is returned. It means the server process started but the LSP initialization sequence did not complete.

Source

Thrown at internal/lsp/client.go:286

	c.diagCountsVersion = 0

	if err := c.createPowernapClient(); err != nil {
		return err
	}

	initCtx, cancel := context.WithTimeout(c.ctx, 30*time.Second)
	defer cancel()

	c.SetServerState(StateStarting)

	// Register handlers before Initialize so servers that send
	// requests during the handshake (e.g. window/workDoneProgress/create)
	// don't crash on an unhandled response.
	c.registerHandlers()

	if err := c.client.Initialize(initCtx, false); err != nil {
		c.SetServerState(StateError)
		return fmt.Errorf("failed to initialize lsp client: %w", err)
	}

	if err := c.WaitForServerReady(initCtx); err != nil {
		slog.Error("Server failed to become ready after restart", "name", c.name, "error", err)
		c.SetServerState(StateError)
		return err
	}

	for _, uri := range openFiles {
		if err := c.OpenFile(initCtx, uri); err != nil {
			slog.Warn("Failed to reopen file after restart", "file", uri, "error", err)
		}
	}
	return nil
}

// ServerState represents the state of an LSP server
type ServerState int

View on GitHub (pinned to 7944b8e522)

Solutions

Run the server binary manually with the same args and cwd to see its startup errors.
Check the server logs/verbose output for why initialize failed or crashed.
Increase the initialization context timeout in Restart.
Pin a known-compatible LSP server version if a recent upgrade broke the handshake.
Verify config args/env passed to the server are correct for its version.

Example fix

// before
initCtx, cancel := context.WithTimeout(ctx, 5*time.Second)

// after
initCtx, cancel := context.WithTimeout(ctx, 30*time.Second)

Defensive patterns

Strategy: retry

Validate before calling

// Ensure the server can at least start before initializing
out, err := exec.CommandContext(ctx, cmd, args...).CombinedOutput()
_ = out // inspect for immediate startup errors if err != nil

Type guard

func initState(err error) bool {
    return client.State() == lsp.StateError // set by Restart on initialize failure
}

Try / catch

if err := client.Restart(ctx); err != nil {
    if strings.Contains(err.Error(), "failed to initialize lsp client") {
        slog.Warn("LSP initialize failed; retrying once", "error", err)
        time.Sleep(2 * time.Second)
        if retryErr := client.Restart(ctx); retryErr != nil {
            return retryErr
        }
    }
}

Prevention

Use generous initialization timeouts, especially on large workspaces.
Capture server stderr to a log file so initialize failures are diagnosable.
After server upgrades, re-test the handshake before deploying config changes.

When it happens

Trigger: Calling Restart (or New's startup path) where c.client.Initialize(initCtx, false) returns an error — server crashed on startup, responded with an error, closed the connection during handshake, or the initCtx expired mid-initialization.

Common situations: LSP server version incompatible with the request capabilities; server immediately exits due to bad args/env; server binary is a wrapper script that fails; context deadline too short for slow-starting servers.

Related errors

AI-assisted analysis of charmbracelet/crush@7944b8e522 (2026-08-29). Data as JSON: /api/errors/39a529fda69b2f5b. Report an issue: GitHub.