charmbracelet/crush · error

agent coordinator not initialized

Error message

agent coordinator not initialized

What it means

AppWorkspace.AgentRun refuses to run when the app's AgentCoordinator is nil. The coordinator owns named agents and LLM sessions; without it no prompt can be dispatched, so the workspace returns this sentinel error instead of panicking on a nil pointer.

Source

Thrown at internal/workspace/app_workspace.go:108

	if err := w.app.Messages.FlushAll(ctx); err != nil {
		return nil, err
	}
	return w.app.Messages.List(ctx, sessionID)
}

func (w *AppWorkspace) ListUserMessages(ctx context.Context, sessionID string) ([]message.Message, error) {
	return w.app.Messages.ListUserMessages(ctx, sessionID)
}

func (w *AppWorkspace) ListAllUserMessages(ctx context.Context) ([]message.Message, error) {
	return w.app.Messages.ListAllUserMessages(ctx)
}

// -- Agent --

func (w *AppWorkspace) AgentRun(ctx context.Context, sessionID, prompt string, attachments ...message.Attachment) error {
	if w.app.AgentCoordinator == nil {
		return errors.New("agent coordinator not initialized")
	}
	_, err := w.app.AgentCoordinator.Run(ctx, sessionID, prompt, attachments...)
	return err
}

func (w *AppWorkspace) AgentRunShellCommand(ctx context.Context, sessionID, command string, termWidth int, onProgress func(string), isFirstMessage bool) (proto.ShellCommandResponse, error) {
	var persist shell.PersistFunc
	if sessionID != "" {
		persist = func(cmd, output string, exitCode int) error {
			return shell.PersistOutput(ctx, w.app.Messages, sessionID, cmd, output, exitCode)
		}
	}

	opts := shell.RunOptions{
		Command:   command,
		Cwd:       w.store.WorkingDir(),
		TermWidth: termWidth,
	}

View on GitHub (pinned to 7944b8e522)

Solutions

1. Ensure app initialization (which builds AgentCoordinator) completed before calling AgentRun
2. Check startup error handling — a failed init that skipped coordinator creation is the root cause
3. In tests/embedded use, populate w.app.AgentCoordinator with a real or fake coordinator

Example fix

// before
_, err := w.app.AgentCoordinator.Run(ctx, sessionID, prompt, attachments...)
// after
if w.app.AgentCoordinator == nil {
	return errors.New("agent coordinator not initialized")
}
_, err := w.app.AgentCoordinator.Run(ctx, sessionID, prompt, attachments...)

if w.app.AgentCoordinator == nil {
	return errors.New("agent coordinator not initialized")
}
err := w.AgentRun(ctx, sessionID, prompt, attachments...)

func (w *AppWorkspace) CoordinatorReady() bool { return w.app.AgentCoordinator != nil }

if err := w.AgentRun(ctx, sessionID, prompt); err != nil {
	if err.Error() == "agent coordinator not initialized" {
		// wait for app init or reinitialize the app
	}
}

When it happens

Trigger: Calling AgentRun before app.Dial/initialization created the coordinator, or after shutdown cleared it; constructing AppWorkspace with a partially initialized app struct (e.g. in tests or headless/embedded use).

Common situations: Invoking agent runs via the workspace API during startup races; embedders calling AgentRun on an app that failed mid-initialization; tests stubbing the app without a coordinator.

Related errors

• failed to initialize agent: %w
• agent configuration not found
• errors.New(s.Error)
• failed to initialize coder agent: %w
• cannot continue an agent tool session: %s

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