hasura/graphql-engine · error

parsing metadata to yaml: %w

Error message

parsing metadata to yaml: %w

What it means

When exporting in YAML mode, the CLI converts the JSON metadata returned by the server into YAML via metadatautil.JSONToYAML. This error means that conversion failed — typically because the server's metadata contains YAML-incompatible structures (non-string map keys like numbers/booleans, which YAML round-trips badly) or the JSON payload was malformed.

Source

Thrown at cli/pkg/metadata/mode_handlers.go:294

func export(p *ProjectMetadata, mode cli.MetadataMode) (io.Reader, error) {
	var op errors.Op = "metadata.export"

	metadata, err := p.ec.APIClient.V1Metadata.ExportMetadata()
	if err != nil {
		return nil, errors.E(op, fmt.Errorf("exporting metadata from server: %w", err))
	}

	var metadataBytes []byte

	metadataBytes, err = io.ReadAll(metadata)
	if err != nil {
		return nil, errors.E(op, fmt.Errorf("reading metadata from response: %w", err))
	}

	if mode == cli.MetadataModeYAML {
		metadataBytes, err = metadatautil.JSONToYAML(metadataBytes)
		if err != nil {
			return nil, errors.E(op, fmt.Errorf("parsing metadata to yaml: %w", err))
		}
	}

	return bytes.NewReader(metadataBytes), nil
}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Export in JSON mode instead (default) — it preserves the exact server representation
2. Inspect the exported JSON to find keys that are not strings (numbers/booleans as object keys)
3. Update the CLI: newer releases fixed known JSONToYAML round-trip issues
4. If a specific object triggers it, simplify/remove that object from metadata and retry

Example fix

# before
hasura metadata export  # with a config forcing YAML mode -> parsing metadata to yaml
# after
hasura metadata export  # default JSON mode; or fix metadata so keys are YAML-safe

if _, err := pm.Export(ctx, cli.MetadataModeYAML); err != nil {
    if strings.Contains(err.Error(), "parsing metadata to yaml") {
        r, err = pm.Export(ctx, cli.MetadataModeJSON) // fallback preserves data
    }
}

When it happens

Trigger: Calling Export with mode == cli.MetadataModeYAML when the exported JSON metadata has map keys that cannot be represented as YAML scalar keys (e.g. numeric boolean keys from naming conventions/remote schema configs), or the payload contains data the YAML marshaller rejects.

Common situations: Projects using GraphQL naming conventions with boolean options that become map keys in metadata; metadata containing large numbers that lose precision; exotic remote schema or action definitions produced by plugins that serialize oddly.

Related errors

• parsing yaml metadata to json: %w
• error getting actions file content: %w
• error in creating action: %w
• parsing metadata to yaml: %w
• parsing yaml metadata to json: %w

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/e94d764ecfa1c593. Report an issue: GitHub.