googleapis/mcp-toolbox · critical

unable to parse YAML: %s

Error message

unable to parse YAML: %s

What it means

UnmarshalPrimitiveConfig parses the raw tools.yaml bytes with the yaml parser (goccy/go-yaml). If parser.ParseBytes fails, the whole config cannot be read and the server aborts with this error, which embeds the formatted YAML error including line/column context.

Source

Thrown at internal/server/config.go:185

type GroupConfigs map[string]group.GroupConfig

func UnmarshalPrimitiveConfig(ctx context.Context, raw []byte) (SourceConfigs, AuthServiceConfigs, EmbeddingModelConfigs, ToolConfigs, PromptConfigs, GroupConfigs, error) {
	// prepare configs map
	var sourceConfigs SourceConfigs
	var authServiceConfigs AuthServiceConfigs
	var embeddingModelConfigs EmbeddingModelConfigs
	var toolConfigs ToolConfigs
	var promptConfigs PromptConfigs
	var groupConfigs GroupConfigs
	// Legacy `kind: toolset` configs are collected here as tools-only groups, then
	// folded into groupConfigs after the loop so explicit `kind: group` definitions
	// take precedence regardless of document order.
	var toolsetGroups map[string]group.GroupConfig
	// promptset configs is not yet supported

	file, err := parser.ParseBytes(raw, 0)
	if err != nil {
		return nil, nil, nil, nil, nil, nil, fmt.Errorf("unable to parse YAML: %s", yaml.FormatError(err, false, false))
	}

	decoder := yaml.NewDecoder(bytes.NewReader(raw))
	for index, doc := range file.Docs {
		if doc == nil || doc.Body == nil {
			continue
		}
		docIndex := index + 1
		var resource map[string]any
		if err := decoder.DecodeFromNodeContext(ctx, doc.Body, &resource); err != nil {
			if len(file.Docs) > 1 {
				return nil, nil, nil, nil, nil, nil, fmt.Errorf("document %d: %s", docIndex, yaml.FormatError(err, false, false))
			}
			return nil, nil, nil, nil, nil, nil, fmt.Errorf("unable to decode YAML document: %s", yaml.FormatError(err, false, false))
		}
		var kind, name string
		var ok bool
		if kind, ok = resource["kind"].(string); !ok {

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Read the formatted error for the exact line/column and fix the YAML syntax there
2. Replace tabs with spaces and fix indentation to consistent 2-space steps
3. Quote values that begin with special YAML characters (e.g. '*', '@', ':')
4. Validate the file with a YAML linter or `toolbox --tools-file my.yaml` before deploying

Example fix

// before
sources:
	my-pg:
	kind: postgres
// after
sources:
  my-pg:
    kind: postgres

const yaml = require('yaml');
try { yaml.parse(fs.readFileSync('tools.yaml', 'utf8')); }
catch (e) { console.error('tools.yaml syntax error:', e.message); process.exit(1); }

When it happens

Trigger: Loading a tools.yaml with syntax errors: bad indentation, tabs instead of spaces, unquoted special characters (@, *, :) at value start, unterminated strings, or invalid YAML anchors.

Common situations: Hand-edited YAML configs, copy-pasting config from docs with wrong indentation, editor inserting tabs, missing space after a colon, unescaped template characters.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• document %d: %s
• unable to decode YAML document: %s
• environment variable not found: %s
• environment variables not found: - %s
• error parsing environment variables: %s

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