charmbracelet/crush · error

timeout waiting for agent readiness

Error message

timeout waiting for agent readiness

What it means

Thrown by waitForAgent (internal/cmd/run.go:471) when the 30-second timeout elapses while the agent is still polling successfully but never reports IsReady=true. Unlike the sibling error at line 469, there is no underlying transport error; the server responds but the agent remains unready.

Source

Thrown at internal/cmd/run.go:471

	}
	return false, nil
}

// waitForAgent polls GetAgentInfo until the agent is ready, with a
// timeout.
func waitForAgent(ctx context.Context, c *client.Client, wsID string) error {
	timeout := time.After(30 * time.Second)
	for {
		info, err := c.GetAgentInfo(ctx, wsID)
		if err == nil && info.IsReady {
			return nil
		}
		select {
		case <-timeout:
			if err != nil {
				return fmt.Errorf("timeout waiting for agent: %w", err)
			}
			return fmt.Errorf("timeout waiting for agent readiness")
		case <-ctx.Done():
			return ctx.Err()
		case <-time.After(200 * time.Millisecond):
		}
	}
}

// overrideModels resolves model strings and updates the workspace
// configuration via the server.
func overrideModels(
	ctx context.Context,
	c *client.Client,
	ws *proto.Workspace,
	largeModel, smallModel string,
) error {
	cfg, err := c.GetConfig(ctx, ws.ID)
	if err != nil {
		return fmt.Errorf("failed to get config: %w", err)

View on GitHub (pinned to 7944b8e522)

Solutions

1. Check server logs for the agent's initialization state to find why IsReady never flips to true
2. Verify MCP/LSP servers and provider configured in the workspace start correctly
3. Retry the command; if it recurs, restart the server/agent process
4. Increase the timeout if initialization is legitimately slow (cold cache, slow network)
5. Report a bug if the agent is permanently wedged despite healthy dependencies

if err := runNonInteractive(...); err != nil {
	if err.Error() == "timeout waiting for agent readiness" {
		// poll GetAgentInfo yourself or restart the server, then retry once
	}
}

When it happens

Trigger: c.GetAgentInfo(ctx, wsID) succeeds (err == nil) every 200ms for 30 seconds, but info.IsReady stays false the entire time; then the timeout channel fires and this error is returned.

Common situations: Agent stuck initializing (LSP or MCP server hang, provider catalog download blocked), server overloaded, agent in a permanent error/retry state server-side, or a stale agent process that will never become ready.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• agent not ready: %w
• timeout waiting for agent: %w
• failed to make request: %w
• failed to initialize coder agent: %w
• failed to wait for MCP initialization: %w

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