What causes "failed to unmarshal generation options from yaml: %w" in googleapis/mcp-toolbox?

Run the YAML through a linter/parser (yq or yamlfmt) to find the exact syntax error at the reported line

failed to unmarshal generation options from yaml: %w

Error message

failed to unmarshal generation options from yaml: %w

What it means

This error is returned by GenerationOptions.UnmarshalYAML when the YAML bytes for the generationOptions block cannot be parsed into a generic map. The tool first tries yaml.Unmarshal into map[string]any; any YAML syntax error (bad indentation, tabs, duplicate keys, invalid scalars) is wrapped with this message. It indicates the tools.yaml config itself is malformed, not an API/runtime failure.

Source

Thrown at internal/tools/cloudgda/cloudgda.go:98

	if err != nil {
		return fmt.Errorf("failed to marshal context map: %w", err)
	}
	q.QueryDataContext = &geminidataanalyticspb.QueryDataContext{}
	if err := protojson.Unmarshal(jsonBytes, q.QueryDataContext); err != nil {
		return fmt.Errorf("failed to unmarshal context to proto: %w", err)
	}
	return nil
}

// GenerationOptions wraps geminidataanalyticspb.GenerationOptions to support YAML decoding via protojson.
type GenerationOptions struct {
	*geminidataanalyticspb.GenerationOptions
}

func (g *GenerationOptions) UnmarshalYAML(b []byte) error {
	var raw map[string]any
	if err := yaml.Unmarshal(b, &raw); err != nil {
		return fmt.Errorf("failed to unmarshal generation options from yaml: %w", err)
	}
	jsonBytes, err := json.Marshal(raw)
	if err != nil {
		return fmt.Errorf("failed to marshal generation options map: %w", err)
	}
	g.GenerationOptions = &geminidataanalyticspb.GenerationOptions{}
	if err := protojson.Unmarshal(jsonBytes, g.GenerationOptions); err != nil {
		return fmt.Errorf("failed to unmarshal generation options to proto: %w", err)
	}
	return nil
}

type Config struct {
	tools.ConfigBase  `yaml:",inline"`
	Type              string                 `yaml:"type" validate:"required"`
	Source            string                 `yaml:"source" validate:"required"`
	Location          string                 `yaml:"location" validate:"required"`
	Context           *QueryDataContext      `yaml:"context" validate:"required"`

View on GitHub (pinned to 8cc6e09de2)

Solutions

Run the YAML through a linter/parser (yq or yamlfmt) to find the exact syntax error at the reported line
Fix indentation to use consistent 2-space indentation, no tabs
Quote scalar values that contain special YAML characters (:, -, #, @, {)
If the value is a nested block, ensure generationOptions is followed by indented child keys, not an inline scalar

Example fix

// before (invalid YAML: tabs and unquoted colon)
generationOptions:
	queryMode: AUTO
	project: my:project
// after
generationOptions:
  queryMode: AUTO
  project: "my:project"

Defensive patterns

Strategy: validation

Validate before calling

import "gopkg.in/yaml.v3"
func validYAML(b []byte) error {
	var m map[string]any
	return yaml.Unmarshal(b, &m)
}

Prevention

Lint tools.yaml with yq or a YAML formatter before starting the server
Use spaces, never tabs, in YAML files
Quote scalars containing : # @ { } characters

When it happens

Trigger: Declaring a cloudgda tool in tools.yaml where the generationOptions value has invalid YAML syntax: tabs instead of spaces, unbalanced quotes or brackets, or a scalar where a mapping is expected (e.g. generationOptions: someString).

Common situations: Hand-editing tools.yaml and breaking indentation; pasting generationOptions from JSON with mismatched quoting; copy-paste introducing tabs; YAML anchors/merge keys mishandled; special characters like '@' or ':' unquoted.

Related errors

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