charmbracelet/crush · error · ErrAgentNotInitialized

coder agent is not initialized

Error message

coder agent is not initialized

What it means

ErrAgentNotInitialized is a sentinel error (errors.New) in internal/workspace indicating the workspace object exists but its coder agent was never configured or initialized — typically because no model was set. It is returned by AgentReadyErr so callers can distinguish this condition from connection-level problems like ErrServerUnreachable.

Source

Thrown at internal/workspace/workspace.go:34

	"github.com/charmbracelet/crush/internal/config"
	"github.com/charmbracelet/crush/internal/history"
	"github.com/charmbracelet/crush/internal/lsp"
	"github.com/charmbracelet/crush/internal/message"
	"github.com/charmbracelet/crush/internal/oauth"
	"github.com/charmbracelet/crush/internal/permission"
	"github.com/charmbracelet/crush/internal/proto"
	"github.com/charmbracelet/crush/internal/question"
	"github.com/charmbracelet/crush/internal/session"
	"github.com/charmbracelet/crush/internal/skills"
)

// Reasons the coder agent may be unavailable, returned by
// Workspace.AgentReadyErr so callers can tell a genuinely
// uninitialized agent apart from a lost server connection.
var (
	// ErrAgentNotInitialized means the workspace exists but its coder
	// agent has not been configured/initialized (e.g. no model set).
	ErrAgentNotInitialized = errors.New("coder agent is not initialized")
	// ErrServerUnreachable means the client could not reach the server
	// to determine the agent's status (server down, or the workspace was
	// torn down out from under the client).
	ErrServerUnreachable = errors.New("lost connection to the crush server")
	// ErrWorkspaceGone means the server is reachable but no longer knows
	// this client's workspace: it was torn down, or the server was
	// replaced underneath the client. The subscription loop re-registers
	// the workspace in the background when it sees this.
	ErrWorkspaceGone = errors.New("the server reset this workspace; reconnecting")
	// ErrStreamClosed means an established event stream ended.
	// Resubscribing usually succeeds immediately, but events published in
	// the meantime are lost for good, so the client treats it as a
	// degraded link that requires a resync.
	ErrStreamClosed = errors.New("the event stream closed; reconnecting")
)

// ConnectionState describes the health of the client-server link as
// reported by the [ClientWorkspace] subscription loop.

View on GitHub (pinned to 7944b8e522)

Solutions

  1. Initialize/configure the coder agent for the workspace (set a model) before calling SendMessage or SummarizeSession
  2. Call Workspace.AgentReadyErr first and branch on errors.Is to surface a user-facing 'pick a model' prompt
  3. Check your crush config defines a provider and model so agent initialization succeeds at startup

Example fix

// before
resp, err := ws.SendMessage(ctx, sessionID, text)
// after
if err := ws.AgentReadyErr(ctx); err != nil {
    if errors.Is(err, workspace.ErrAgentNotInitialized) {
        return nil, fmt.Errorf("select a model before chatting: %w", err)
    }
    return nil, err
}
resp, err := ws.SendMessage(ctx, sessionID, text)
Defensive patterns

Strategy: type-guard

Validate before calling

if err := ws.AgentReadyErr(ctx); err != nil {
    if errors.Is(err, workspace.ErrAgentNotInitialized) {
        // prompt user to configure a model
    }
}

Type guard

func isAgentNotInitialized(err error) bool { return errors.Is(err, workspace.ErrAgentNotInitialized) }

Try / catch

if err != nil {
    if errors.Is(err, workspace.ErrAgentNotInitialized) { /* configure model */ }
    return err
}

Prevention

When it happens

Trigger: Calling SendMessage or SummarizeSession on a workspace whose coder agent has no model configured; any code path (including handleError and AgentReadyErr) that checks agent readiness before the agent exists.

Common situations: Running a client against a workspace created before a model was chosen; config files missing a provider/model entry; racing a workspace start before agent setup completes in tests like TestSendMessage_AgentNotInitialized.

Related errors

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