charmbracelet/crush · error

failed to refresh MCP prompts: %w

Error message

failed to refresh MCP prompts: %w

What it means

This error is returned by Client.MCPRefreshPrompts when the HTTP POST to /workspaces/{id}/mcp/refresh-prompts fails before a response is available. The underlying transport error (connection refused, DNS failure, timeout, cancelled context) is wrapped with %w. It means the refresh-prompts request never got a response from the server.

Source

Thrown at internal/client/proto.go:399

	if rsp.StatusCode != http.StatusOK {
		var e proto.Error
		if err := json.NewDecoder(rsp.Body).Decode(&e); err == nil && e.Message != "" {
			return fmt.Errorf("failed to authenticate MCP: %s", e.Message)
		}
		return fmt.Errorf("failed to authenticate MCP: status code %d", rsp.StatusCode)
	}
	return nil
}

// MCPRefreshPrompts refreshes prompts for a named MCP client.
func (c *Client) MCPRefreshPrompts(ctx context.Context, id, name string) error {
	rsp, err := c.post(ctx, fmt.Sprintf("/workspaces/%s/mcp/refresh-prompts", 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 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)
	}

View on GitHub (pinned to 7944b8e522)

Solutions

1. Inspect the wrapped error to identify whether it is a connection, DNS, TLS, or context failure
2. Verify the API server is running and reachable at the configured base URL
3. Retry the call with a fresh, adequately-long context after connectivity is restored
4. Confirm the workspace id and MCP name exist; fix client configuration if the endpoint host/port is wrong

Example fix

// before
err := client.MCPRefreshPrompts(ctx, "ws-123", "github") // fires even when offline

// after
if err := pingEndpoint(ctx); err != nil {
    return fmt.Errorf("server unreachable, skipping prompt refresh: %w", err)
}
if err := client.MCPRefreshPrompts(ctx, "ws-123", "github"); err != nil {
    return fmt.Errorf("refresh prompts: %w", err)
}

// Confirm connectivity and a live context before refreshing
func readyToRefresh(ctx context.Context, baseURL string) error {
    if err := ctx.Err(); err != nil { return fmt.Errorf("context not usable: %w", err) }
    return serverReachable(ctx, baseURL) // HEAD probe with short timeout
}

// Detect transport-level causes in the wrapped error
func isRefreshTransportErr(err error) bool {
    var netErr net.Error
    return err != nil && strings.HasPrefix(err.Error(), "failed to refresh MCP prompts: ") &&
        (errors.As(err, &netErr) || errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled))
}

// Bounded retry for transient transport failures
err := client.MCPRefreshPrompts(ctx, wsID, name)
for attempt := 0; err != nil && isRefreshTransportErr(err) && attempt < 3; attempt++ {
    time.Sleep(time.Duration(1<<attempt) * time.Second)
    err = client.MCPRefreshPrompts(ctx, wsID, name)
}
if err != nil { return fmt.Errorf("prompt refresh: %w", err) }

When it happens

Trigger: Calling MCPRefreshPrompts(ctx, id, name) while the server is unreachable, the network drops mid-request, TLS handshake fails, the base URL is misconfigured, or ctx is cancelled before the POST completes.

Common situations: Server restarted while the client was connected; laptop switching networks/VPNs; wrong port in client config; context deadline exceeded when the MCP server's prompt discovery is slow upstream.

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 authenticate MCP: %w
• failed to get MCP auth URL: %w
• failed to download from URL: %w
• failed to create request: %w
• failed to fetch URL: %w

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