What causes "failed to initialize coder agent: %w" in charmbracelet/crush?

Read the wrapped cause (%w chain) printed below this message — it names the actual failure.

failed to initialize coder agent: %w

Error message

failed to initialize coder agent: %w

What it means

App.New wraps any failure from app.InitCoderAgent — the step that constructs the primary 'coder' agent (model/provider wiring, tool registration, prompt loading). This means configuration was present (cfg.IsConfigured() passed) but agent construction failed, so the whole application cannot start.

Source

Thrown at internal/app/app.go:171

		Messages:          app.Messages,
	})

	// Release the shared database connection on shutdown. The pool
	// closes the underlying *sql.DB when the last reference is released.
	dataDir := cfg.Options.DataDirectory
	app.cleanupFuncs = append(
		app.cleanupFuncs,
		func(context.Context) error { return db.Release(dataDir) },
		func(ctx context.Context) error { return mcp.Close(ctx) },
	)

	// TODO: remove the concept of agent config, most likely.
	if !cfg.IsConfigured() {
		slog.Warn("No agent configuration found")
		return app, nil
	}
	if err := app.InitCoderAgent(ctx); err != nil {
		return nil, fmt.Errorf("failed to initialize coder agent: %w", err)
	}

	// Set up callback for LSP state updates.
	app.LSPManager.SetCallback(func(name string, client *lsp.Client) {
		if client == nil {
			updateLSPState(name, lsp.StateUnstarted, nil, nil, 0)
			return
		}
		client.SetDiagnosticsCallback(updateLSPDiagnostics)
		updateLSPState(name, client.GetServerState(), nil, client, 0)
	})

	// TrackConfigured must run after SetCallback so the callback is already
	// installed when configured-but-not-yet-started LSPs are announced.
	go app.LSPManager.TrackConfigured(ctx)

	return app, nil
}

View on GitHub (pinned to 7944b8e522)

Solutions

Read the wrapped cause (%w chain) printed below this message — it names the actual failure.
Validate crushrc/crush.json: provider and model IDs must match the provider catalog (crush models).
Ensure required API key env vars are set in the shell running crush (ANTHROPIC_API_KEY, etc.).
Check network access to the provider catalog; configure a local snapshot if offline.

Example fix

// before (crushrc)
provider anthropic
model anthropic/claude-3-7-sonnet-typo

// after
provider anthropic
  api_key_env ANTHROPIC_API_KEY
model anthropic/claude-sonnet-4-20250514

Defensive patterns

Strategy: validation

Validate before calling

if !cfg.IsConfigured() {
    return fmt.Errorf("configure a provider and model in crushrc before starting")
}
// verify required keys
for _, k := range []string{"ANTHROPIC_API_KEY"} {
    if os.Getenv(k) == "" {
        return fmt.Errorf("%s is not set", k)
    }
}

Try / catch

app, err := app.New(ctx, opts)
if err != nil {
    slog.Error("startup failed", "err", err) // %w chain names the real cause
    os.Exit(1)
}

Prevention

Run `crush models` to confirm provider/model IDs exist in the catalog before referencing them.
Export API keys in the shell profile that launches crush.
Validate crushrc syntax after edits; keep model IDs updated after catalog changes.
Provide an offline catalog snapshot for air-gapped environments.

When it happens

Trigger: InitCoderAgent returns an error: invalid provider/model IDs in crushrc/crush.json, missing API key env vars, failed provider catalog fetch, or a tool/LSP dependency failing to initialize.

Common situations: Renamed or removed model IDs after a provider catalog update; API keys not exported in the shell; malformed provider config block in crushrc; offline environments unable to fetch the model catalog.

Related errors

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