What causes "invalid generated yaml structure" in router-for-me/CLIProxyAPI?

If you forked or vendored yaml.v3, restore the standard library version from go.mod.

invalid generated yaml structure

Error message

invalid generated yaml structure

What it means

Thrown when the config struct, marshaled back to YAML and re-parsed, does not yield a valid document node. This is an internal invariant check on the 'generated' tree (the sanitized current config) used for merging back into the original file. Because yaml.Marshal of the Config struct always emits a document, hitting this indicates memory corruption, a nil-producing custom marshaller, or an upstream library inconsistency rather than a user config mistake.

Source

Thrown at internal/config/config_yaml.go:43

	}
	if original.Kind != yaml.DocumentNode || len(original.Content) == 0 {
		return fmt.Errorf("invalid yaml document structure")
	}
	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])

View on GitHub (pinned to 78f0c4079e)

Solutions

If you forked or vendored yaml.v3, restore the standard library version from go.mod.
Check any custom MarshalYAML implementations you added to Config sub-structs return non-nil values.
Run 'go mod tidy' and rebuild with the pinned dependencies.
If it persists on stock code, report it upstream with the config that reproduces it.

Defensive patterns

Strategy: validation

Prevention

Use the pinned yaml.v3 dependency from go.mod; do not vendor forks.
Ensure custom MarshalYAML methods never return nil or invalid nodes.
Run 'go mod tidy' after dependency changes.

When it happens

Trigger: Essentially unreachable in normal operation: it fires only if yaml.Marshal(persistCfg) produces output that unmarshals to a non-document or a document with nil/empty content — e.g. a custom MarshalYAML on an embedded struct returning a nil node, or a yaml.v3 version mismatch.

Common situations: Building from source with an incompatible fork of gopkg.in/yaml.v3; a plugin or fork adding a type whose MarshalYAML returns invalid output; extremely unlikely for stock releases.

Related errors

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