hasura/graphql-engine · error

parsing metadata to yaml: %w

Error message

parsing metadata to yaml: %w

What it means

When exporting metadata in YAML mode, the server's JSON metadata must be converted to YAML via metadatautil.JSONToYAML. This error means that conversion failed — practically, because the JSON returned by the server is malformed or contains structures the converter cannot marshal to YAML.

Source

Thrown at cli/commands/metadata_handlers.go:333

func export(o *MetadataExportOptions, mode cli.MetadataMode) error {
	var op errors.Op = "commands.export"

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

	var metadataBytes []byte

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

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

	err = os.WriteFile(o.EC.MetadataFile, metadataBytes, os.ModePerm)
	if err != nil {
		return errors.E(op, fmt.Errorf("writing metadata to file: %w", err))
	}

	return nil
}

func apply(o *MetadataApplyOptions, mode cli.MetadataMode) error {
	var (
		op                 errors.Op = "commands.apply"
		localMetadataBytes []byte
		err                error
	)

View on GitHub (pinned to 724551b9ae)

Solutions

1. Export in JSON format first to inspect the raw document and confirm it is valid JSON
2. Update the CLI to a version matching the server's metadata API version
3. If the JSON is malformed, investigate the server-side metadata state (possible inconsistency) with `metadata inconsistency list`
4. Report to CLI maintainers if the JSON is valid but conversion still fails (converter bug)

Example fix

# before
hasura metadata export -o yaml  # parsing metadata to yaml
# after
hasura metadata export -o json  # inspect raw JSON, then convert locally with yq

// validate JSON before YAML conversion in your own tooling
var v any
if err := json.Unmarshal(metadataBytes, &v); err != nil {
  // export as JSON instead of YAML
}

if err := export(o, cli.MetadataModeYAML); err != nil {
  if strings.Contains(err.Error(), "parsing metadata to yaml") {
    return export(o, cli.MetadataModeJSON) // fallback format
  }
}

When it happens

Trigger: Running `metadata export --o yaml` (or equivalent) where the fetched metadata bytes are not valid JSON or fail YAML marshalling: truncated server response, unexpected JSON types, encoding issues.

Common situations: Server returning an error page or truncated body that still reads successfully but is not the expected JSON document; very old/new server versions emitting JSON structures the CLI converter does not understand; BOM or encoding artifacts in the response.

Related errors

• reading server metadata: %w
• exporting metadata from server: %w
• reading metadata from response: %w
• writing metadata to file: %w
• parsing yaml metadata to json: %w

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