failed to initiate session agent processing: status code %d

Error message

failed to initiate session agent processing: status code %d

What it means

Thrown by Client.InitiateAgentProcessing when the server responded to POST /workspaces/{id}/agent/init with a non-200 status code. The body is discarded, so the caller only knows the numeric status. This means the server received and rejected the init request. Called by InitCoderAgent and InitCoderAgentNonInteractive.

Source

Thrown at internal/client/proto.go:585

		return fmt.Errorf("failed to summarize session: %w", err)
	}
	defer rsp.Body.Close()
	if rsp.StatusCode != http.StatusOK {
		return fmt.Errorf("failed to summarize session: status code %d", rsp.StatusCode)
	}
	return nil
}

// InitiateAgentProcessing triggers agent initialization on the server.
func (c *Client) InitiateAgentProcessing(ctx context.Context, id string, interactive bool) error {
	body := jsonBody(proto.AgentInitRequest{Interactive: interactive})
	rsp, err := c.post(ctx, fmt.Sprintf("/workspaces/%s/agent/init", id), nil, body, http.Header{"Content-Type": []string{"application/json"}})
	if err != nil {
		return fmt.Errorf("failed to initiate session agent processing: %w", err)
	}
	defer rsp.Body.Close()
	if rsp.StatusCode != http.StatusOK {
		return fmt.Errorf("failed to initiate session agent processing: status code %d", rsp.StatusCode)
	}
	return nil
}

// ListMessages retrieves all messages for a session as proto types.
func (c *Client) ListMessages(ctx context.Context, id string, sessionID string) ([]proto.Message, error) {
	rsp, err := c.get(ctx, fmt.Sprintf("/workspaces/%s/sessions/%s/messages", id, sessionID), nil, nil)
	if err != nil {
		return nil, fmt.Errorf("failed to get messages: %w", err)
	}
	defer rsp.Body.Close()
	if rsp.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("failed to get messages: status code %d", rsp.StatusCode)
	}
	var msgs []proto.Message
	if err := json.NewDecoder(rsp.Body).Decode(&msgs); err != nil && !errors.Is(err, io.EOF) {
		return nil, fmt.Errorf("failed to decode messages: %w", err)
	}

View on GitHub (pinned to 7944b8e522)

Solutions

Re-produce the request with curl to capture the response body and exact status code.
Verify the workspace id exists and the client/server versions match (route compatibility).
Check server logs for the agent-init failure cause (e.g. missing provider credentials).
Fix authentication (refresh token / re-login) if the status is 401 or 403.

Example fix

// before
err := client.InitiateAgentProcessing(ctx, wsID, false)
if err != nil {
    return err
}
// after: fail fast with a contextual message including the status
if err := client.InitiateAgentProcessing(ctx, wsID, false); err != nil {
    if strings.Contains(err.Error(), "status code 401") {
        return fmt.Errorf("agent init rejected: re-authenticate and retry: %w", err)
    }
    return fmt.Errorf("agent init failed for workspace %s: %w", wsID, err)
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Confirm workspace exists before init
_, err := client.GetSession(ctx, wsID, anyKnownSessionID)
if err != nil {
    return fmt.Errorf("workspace %s unreachable or invalid — fix before agent init", wsID)
}
// Ensure provider credentials are configured server-side
if os.Getenv("ANTHROPIC_API_KEY") == "" && os.Getenv("OPENAI_API_KEY") == "" {
    return errors.New("no provider credentials configured for agent init")
}

Type guard

func statusOf(err error) int {
    var code int
    if _, scanErr := fmt.Sscanf(err.Error(), "failed to initiate session agent processing: status code %d", &code); scanErr == nil {
        return code
    }
    return 0
}

Try / catch

err := client.InitiateAgentProcessing(ctx, wsID, interactive)
if err != nil {
    switch statusOf(err) {
    case 404:
        return fmt.Errorf("workspace %q not found: check client/server route compatibility", wsID)
    case 401, 403:
        return ErrAuthenticationRequired
    case 500:
        return fmt.Errorf("agent init failed server-side: check server logs (credentials?)"): %w", err)
    }
    return err
}

Prevention

Match client and server versions to avoid route mismatches (404)
Configure provider API keys before attempting agent init
Reproduce failed inits with curl to read the response body the client discards
Treat 401/403 as re-auth prompts, not retryable faults

When it happens

Trigger: Calling InitiateAgentProcessing with an unknown workspace id (404), when the agent is already initialized or in a bad state (409/500), with auth failures (401/403), or when the server's agent setup fails internally (500) such as missing provider credentials.

Common situations: Re-running init against a stale/deleted workspace; provider API keys not configured on the server so agent startup fails with 500; route mismatch after a client/server version skew (404); expired auth token (401).

Related errors

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