failed to clear session agent queued prompts: status code %d

Error message

failed to clear session agent queued prompts: status code %d

What it means

ClearAgentSessionQueuedPrompts expects HTTP 200; any other status becomes this error with the code embedded. The server received the clear request but did not succeed.

Source

Thrown at internal/client/proto.go:451

	if rsp.StatusCode != http.StatusOK {
		return 0, fmt.Errorf("failed to get session agent queued prompts: status code %d", rsp.StatusCode)
	}
	var count int
	if err := json.NewDecoder(rsp.Body).Decode(&count); err != nil {
		return 0, fmt.Errorf("failed to decode session agent queued prompts: %w", err)
	}
	return count, nil
}

// ClearAgentSessionQueuedPrompts clears the queued prompts for a session.
func (c *Client) ClearAgentSessionQueuedPrompts(ctx context.Context, id string, sessionID string) error {
	rsp, err := c.post(ctx, fmt.Sprintf("/workspaces/%s/agent/sessions/%s/prompts/clear", id, sessionID), nil, nil, nil)
	if err != nil {
		return fmt.Errorf("failed to clear session agent queued prompts: %w", err)
	}
	defer rsp.Body.Close()
	if rsp.StatusCode != http.StatusOK {
		return fmt.Errorf("failed to clear session agent queued prompts: status code %d", rsp.StatusCode)
	}
	return nil
}

// GetAgentInfo retrieves the agent status for a workspace.
func (c *Client) GetAgentInfo(ctx context.Context, id string) (*proto.AgentInfo, error) {
	rsp, err := c.get(ctx, fmt.Sprintf("/workspaces/%s/agent", id), nil, nil)
	if err != nil {
		return nil, fmt.Errorf("failed to get agent status: %w", err)
	}
	defer rsp.Body.Close()
	if err := checkStatus(rsp); err != nil {
		return nil, fmt.Errorf("failed to get agent status: %w", err)
	}
	var info proto.AgentInfo
	if err := json.NewDecoder(rsp.Body).Decode(&info); err != nil {
		return nil, fmt.Errorf("failed to decode agent status: %w", err)
	}

View on GitHub (pinned to 7944b8e522)

Solutions

Treat 404 as 'session gone' and skip clearing
Re-authenticate on 401/403
Check server logs for the 5xx cause
Retry transient failures with backoff

Defensive patterns

Strategy: try-catch

Validate before calling

if sessionID == "" { return errors.New("session ID required to clear queue") }

Type guard

func clearStatusCode(err error) int {
	var code int
	pattern := "failed to clear session agent queued prompts: status code %d"
	if _, e := fmt.Sscanf(err.Error(), pattern, &code); e == nil { return code }
	return 0
}

Try / catch

err := client.ClearAgentSessionQueuedPrompts(ctx, wsID, sid)
if err != nil {
	switch clearStatusCode(err) {
	case http.StatusNotFound: // session gone, ignore
	case http.StatusUnauthorized: reauthAndRetry()
	default: return err
	}
}

Prevention

Skip clearing sessions that already completed
Refresh auth tokens during long runs
Check server logs for 5xx
Distinguish status errors from transport errors

When it happens

Trigger: POST returns 404 for an unknown/finished session, 401/403 on auth failure, or 500 if the server cannot reset the agent queue.

Common situations: Clearing the queue of a session that already completed; expired credentials; server-side agent in a broken state.

Related errors

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