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

Inspect recent changes to the payload map for non-JSON-serializable values (channels, funcs, cycles).

failed to marshal schema query: %w

Error message

failed to marshal schema query: %w

What it means

getSchemaFromPipeline builds a JSON payload describing a get_schema pipeline request (collection + semantics map) using json.Marshal before POSTing it to the Firestore executePipeline API. This error is thrown if marshaling that simple map[string]string fails — practically only when the encoder cannot serialize the value, which for a map[string]string essentially never happens with valid keys.

Source

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

			})
		}

		result = append(result, CollectionSchema{
			Collection: collName,
			Fields:     fields,
		})
	}

	return result, nil
}

func (s *Source) getSchemaFromPipeline(ctx context.Context, collection string) (CollectionSchema, error) {
	getSchemaQueryBytes, err := json.Marshal(map[string]string{
		"collection": collection,
		"semantics":  "mongodb",
	})
	if err != nil {
		return CollectionSchema{}, fmt.Errorf("failed to marshal schema query: %w", err)
	}

	payload := map[string]any{
		"structuredPipeline": map[string]any{
			"pipeline": map[string]any{
				"stages": []map[string]any{
					{
						"name": "get_schema",
						"args": []map[string]any{
							{
								"stringValue": string(getSchemaQueryBytes),
							},
						},
					},
				},
			},
		},
	}

View on GitHub (pinned to 8cc6e09de2)

Solutions

Inspect recent changes to the payload map for non-JSON-serializable values (channels, funcs, cycles).
Ensure collection is a plain string, not a custom string type with a broken MarshalJSON.
If unexplainable, log err in the wrapped error and test json.Marshal on the payload in isolation.

Example fix

// before: custom type breaks marshaling
collection := myCollectionType("users")
getSchemaQueryBytes, err := json.Marshal(map[string]string{"collection": string-impossible...})
// after: pass a plain string
collection := "users"
getSchemaQueryBytes, err := json.Marshal(map[string]string{"collection": collection, "semantics": "mongodb"})

Defensive patterns

Strategy: validation

Validate before calling

if _, err := json.Marshal(map[string]string{"collection": coll, "semantics": "mongodb"}); err != nil {
    return fmt.Errorf("schema query payload is not marshalable: %w", err)
}

Try / catch

schema, err := getSchemaFromPipeline(ctx, coll)
if err != nil {
    if strings.Contains(err.Error(), "failed to marshal schema query") {
        // payload construction bug: inspect inputs for non-string values
    }
    return err
}

Prevention

Keep pipeline payload fields as plain strings and JSON-safe types.
Avoid custom string types with MarshalJSON on payload fields.
Cover payload construction with a unit test asserting json.Marshal succeeds.

When it happens

Trigger: json.Marshal of the map {"collection":..., "semantics":"mongodb"} returns an error. With this fixed shape this is nearly impossible; it would require an unsupported value type, which this call site cannot produce.

Common situations: Developers who modified the payload to include unsupported types (e.g. channels, funcs, cyclic structures) when extending the query; otherwise seen only in pathological runtime conditions.

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/1038eb026a0967a2. Report an issue: GitHub.