What causes "failed to marshal pipeline payload: %w" in googleapis/mcp-toolbox?

Inspect the payload construction for non-serializable values (channels, funcs, cyclic references).

failed to marshal pipeline payload

Error message

failed to marshal pipeline payload: %w

What it means

ExecuteMQL constructs a structuredPipeline payload wrapping the MQL query and marshals it with json.Marshal before creating the HTTP request. This error is thrown when that marshaling fails, wrapping the underlying json error.

Solutions

Inspect the payload construction for non-serializable values (channels, funcs, cyclic references).
Ensure the query string and any injected parameters are plain strings/JSON-safe types.
Test json.Marshal(payload) in isolation to surface the exact offending field from the wrapped error.

Example fix

// before: injecting a non-serializable value
payload["params"] = someFunc
// after: only JSON-safe values
payload["params"] = map[string]any{"q": queryString}

Defensive patterns

Strategy: validation

Validate before calling

payload := buildExecutePipelinePayload(query)
if _, err := json.Marshal(payload); err != nil {
    return fmt.Errorf("pipeline payload not marshalable before ExecuteMQL: %w", err)
}

Try / catch

result, err := src.ExecuteMQL(ctx, query)
if err != nil {
    if strings.Contains(err.Error(), "failed to marshal pipeline payload") {
        // payload construction bug: inspect payload fields for non-JSON types
    }
    return err
}

Prevention

Only put JSON-safe types (string, number, bool, slice, map) into the pipeline payload.
Write a unit test that marshals the exact payload structure ExecuteMQL builds.
Avoid passing user-supplied objects into the payload without converting to strings first.

When it happens

Trigger: json.Marshal of the payload map fails — practically only when the payload includes values json cannot encode (channels, funcs, cyclic data) which the fixed structure cannot produce; realistically triggered by code modifications introducing non-serializable fields.

Common situations: Custom extensions to ExecuteMQL that inject non-JSON-safe types into the payload; wrapper code passing a struct with unsupported fields.

Understand the failure class

Background: json.Marshal / "failed to marshal" errors in Go: why "unsupported type" happens and how to fix it — this error's family across 22 libraries.

Related errors

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/df933c2b18c37b51. Report an issue: GitHub.

Appendix: source

Thrown at internal/sources/firestore/firestore.go:911

		payload := map[string]any{
			"structuredPipeline": map[string]any{
				"pipeline": map[string]any{
					"stages": []map[string]any{
						{
							"name": "iql",
							"args": []map[string]any{
								{
									"stringValue": mqlQuery,
								},
							},
						},
					},
				},
			},
		}
		bodyBytes, err = json.Marshal(payload)
		if err != nil {
			return nil, fmt.Errorf("failed to marshal pipeline payload: %w", err)
		}
	}

	req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(bodyBytes))
	if err != nil {
		return nil, fmt.Errorf("failed to create HTTP request: %w", err)
	}
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("User-Agent", userAgent)
	req.Header.Set("x-goog-request-params", fmt.Sprintf("project_id=%s&database_id=%s", s.GetProjectId(), s.GetDatabaseId()))
	req.Header.Set("x-goog-firestore-api-requester", "querydata")

	resp, err := httpClient.Do(req)
	if err != nil {
		return nil, fmt.Errorf("failed to execute pipeline request: %w", err)
	}
	defer resp.Body.Close()

View on GitHub (pinned to 8cc6e09de2)