What causes "failed to refresh MCP resources: status code %d" in charmbracelet/crush?

Log/compare the status code in the error message against expected codes (404 => wrong name, 401 => auth)

failed to refresh MCP resources: status code %d

Error message

failed to refresh MCP resources: status code %d

What it means

MCPRefreshResources expects the server to answer HTTP 200. Any other status code (4xx/5xx) is converted to this error with the numeric code embedded. It indicates the server processed the request but rejected or failed it.

Source

Thrown at internal/client/proto.go:420

	if rsp.StatusCode != http.StatusOK {
		return fmt.Errorf("failed to refresh MCP prompts: status code %d", rsp.StatusCode)
	}
	return nil
}

// MCPRefreshResources refreshes resources for a named MCP client.
func (c *Client) MCPRefreshResources(ctx context.Context, id, name string) error {
	rsp, err := c.post(ctx, fmt.Sprintf("/workspaces/%s/mcp/refresh-resources", id), nil,
		jsonBody(struct {
			Name string `json:"name"`
		}{Name: name}),
		http.Header{"Content-Type": []string{"application/json"}})
	if err != nil {
		return fmt.Errorf("failed to refresh MCP resources: %w", err)
	}
	defer rsp.Body.Close()
	if rsp.StatusCode != http.StatusOK {
		return fmt.Errorf("failed to refresh MCP resources: status code %d", rsp.StatusCode)
	}
	return nil
}

// GetAgentSessionQueuedPrompts retrieves the number of queued prompts for a
// session.
func (c *Client) GetAgentSessionQueuedPrompts(ctx context.Context, id string, sessionID string) (int, error) {
	rsp, err := c.get(ctx, fmt.Sprintf("/workspaces/%s/agent/sessions/%s/prompts/queued", id, sessionID), nil, nil)
	if err != nil {
		return 0, fmt.Errorf("failed to get session agent queued prompts: %w", err)
	}
	defer rsp.Body.Close()
	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)

View on GitHub (pinned to 7944b8e522)

Solutions

Log/compare the status code in the error message against expected codes (404 => wrong name, 401 => auth)
Confirm the MCP server name matches one registered in the workspace config
Re-authenticate or refresh credentials if status is 401/403
Check server logs for the 5xx root cause

Defensive patterns

Strategy: try-catch

Validate before calling

if !mcpServerNamePattern.MatchString(name) { return fmt.Errorf("invalid MCP server name %q", name) }

Type guard

func isNon200(err error) (int, bool) {
	s := err.Error()
	var code int
	if n, _ := fmt.Sscanf(s, "failed to refresh MCP resources: status code %d", &code); n == 1 { return code, true }
	return 0, false
}

Try / catch

if err := client.MCPRefreshResources(ctx, wsID, name); err != nil {
	var code int
	if _, ok := fmt.Sscanf(err.Error(), "failed to refresh MCP resources: status code %d", &code); ok && code == http.StatusNotFound {
		// wrong MCP server name — fix config
	}
}

Prevention

Keep MCP server names in config consistent with the server side
Re-authenticate before long-running sessions
Check server logs when receiving 5xx
Distinguish status-code errors from transport errors by message shape

When it happens

Trigger: Calling MCPRefreshResources when the MCP server name does not exist on the server side (404), auth is rejected (401/403), or the server returns 500 while restarting the MCP connection.

Common situations: Typo in the MCP server name passed to the call; auth token expired; server-side MCP process crashed so refresh cannot complete.

Related errors

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