charmbracelet/crush · error

failed to refresh MCP resources: %w

Error message

failed to refresh MCP resources: %w

What it means

MCPRefreshResources POSTs to /workspaces/{id}/mcp/refresh-resources and wraps any transport-level error from c.post with this message. It means the HTTP request to the server failed before a response status could be evaluated (connection failure, timeout, invalid URL, canceled context). The underlying cause is always wrapped and available via errors.Unwrap.

Source

Thrown at internal/client/proto.go:416

	if err != nil {
		return fmt.Errorf("failed to refresh MCP prompts: %w", err)
	}
	defer rsp.Body.Close()
	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)

View on GitHub (pinned to 7944b8e522)

Solutions

1. Check that the crush/opencode server is running and the client base URL points at the correct host/port
2. Verify the workspace ID passed is valid and URL-safe
3. Retry with a fresh context; add a timeout appropriate for the refresh call
4. Inspect the wrapped cause with errors.Unwrap / %v of the returned error to identify the transport failure

Example fix

// before
err := client.MCPRefreshResources(ctx, wsID, "my-mcp")
// after
ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
defer cancel()
if err := client.MCPRefreshResources(ctx, wsID, "my-mcp"); err != nil {
	log.Printf("refresh failed: %v", errors.Unwrap(err))
}

if wsID == "" { return fmt.Errorf("workspace ID required before MCPRefreshResources") }
if u, err := url.Parse(baseURL); err != nil || u.Host == "" { return fmt.Errorf("invalid server base URL") }

func isTransportErr(err error) bool {
	var ne net.Error
	return errors.As(err, &ne) || errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled) || errors.Is(err, syscall.ECONNREFUSED)
}

err := client.MCPRefreshResources(ctx, wsID, name)
var ne net.Error
if errors.As(err, &ne) || errors.Is(err, context.DeadlineExceeded) {
	// transient: retry with backoff
}

When it happens

Trigger: Calling MCPRefreshResources(ctx, workspaceID, name) when the server is unreachable, the workspace ID is malformed/empty producing a bad URL, the context is canceled/timed out, or a proxy/DNS failure occurs during c.post.

Common situations: Dev server not running or restarted mid-session; wrong base URL or port in client configuration; network drops in CI; passing a workspace ID containing characters needing escaping.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• failed to enable docker MCP: %w
• failed to disable docker MCP: %w
• failed to refresh MCP tools: %w
• failed to read MCP resource: %w
• failed to list MCP prompts: %w

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