router-for-me/CLIProxyAPI · error

expected generated root mapping node

Error message

expected generated root mapping node

What it means

Companion invariant to 'invalid generated yaml structure': after re-parsing the marshaled sanitized config, its root content node must be a MappingNode so the sanitizer can merge it key-by-key into the original document. yaml.Marshal of the Config struct always produces a mapping root, so this error indicates a build/library anomaly (custom marshaller returning a sequence or scalar) rather than a user-editable config problem.

Source

Thrown at internal/config/config_yaml.go:46

	}
	if original.Content[0] == nil || original.Content[0].Kind != yaml.MappingNode {
		return fmt.Errorf("expected root mapping node")
	}

	// Marshal the current cfg to YAML, then unmarshal to a yaml.Node we can merge from.
	rendered, err := yaml.Marshal(persistCfg)
	if err != nil {
		return err
	}
	var generated yaml.Node
	if err = yaml.Unmarshal(rendered, &generated); err != nil {
		return err
	}
	if generated.Kind != yaml.DocumentNode || len(generated.Content) == 0 || generated.Content[0] == nil {
		return fmt.Errorf("invalid generated yaml structure")
	}
	if generated.Content[0].Kind != yaml.MappingNode {
		return fmt.Errorf("expected generated root mapping node")
	}

	// Remove deprecated sections before merging back the sanitized config.
	removeLegacyAuthBlock(original.Content[0])
	removeLegacyOpenAICompatAPIKeys(original.Content[0])
	removeRemovedIntegrationKeys(original.Content[0])
	removeLegacyGenerativeLanguageKeys(original.Content[0])

	pruneMappingToGeneratedKeys(original.Content[0], generated.Content[0], "oauth-excluded-models")
	pruneMappingToGeneratedKeys(original.Content[0], generated.Content[0], "oauth-model-alias")
	pruneMappingToGeneratedKeys(original.Content[0], generated.Content[0], "plugins", "configs")

	// Merge generated into original in-place, preserving comments/order of existing nodes.
	mergeMappingPreserve(original.Content[0], generated.Content[0])
	normalizeCollectionNodeStyles(original.Content[0])

	// Write back.
	f, err := os.Create(configFile)

View on GitHub (pinned to 78f0c4079e)

Solutions

1. Audit any custom MarshalYAML methods added to Config or its embedded structs; make them return mappings.
2. Revert local modifications to internal/config and rebuild.
3. Restore the pinned yaml.v3 dependency ('go mod tidy', rebuild).
4. Report upstream with reproduction details if it occurs on unmodified code.

When it happens

Trigger: Only if a Config sub-type has a custom MarshalYAML that emits a non-mapping root document (e.g. returns a sequence node), or a modified yaml.v3 dependency changes document emission.

Common situations: Custom forks adding exotic marshal behaviour to the top-level config; vendored dependency drift; not seen with the shipped code.

Related errors

• invalid generated yaml structure
• decode codex.live-media-relay.allow-private-remote-ips: %w
• decode codex.live-media-relay.disable-private-remote-ips: %w
• failed to parse config file: %w
• parse plugin enabled: %w

AI-assisted analysis of router-for-me/CLIProxyAPI@78f0c4079e (2026-08-15). Data as JSON: /api/errors/c99e1302af73def4. Report an issue: GitHub.