hasura/graphql-engine · error

parsing local yaml metadata as json: %w

Error message

parsing local yaml metadata as json: %w

What it means

After successfully reading metadata.yaml, the YAML handler converts it to JSON via metadatautil.YAMLToJSON; invalid YAML (or YAML structures unmarshalable to JSON, like non-string map keys) fails here with 'parsing local yaml metadata as json'.

Source

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

	r, err := apply(p, p.ec.MetadataMode)
	if err != nil {
		return nil, errors.E(op, err)
	}

	return r, nil
}

func (m *metadataModeYAMLHandler) Parse(p *ProjectMetadata) (io.Reader, error) {
	var op errors.Op = "metadata.metadataModeYAMLHandler.Parse"

	metadataYAML, err := os.ReadFile(p.ec.MetadataFile)
	if err != nil {
		return nil, errors.E(op, fmt.Errorf("reading metadata file: %w", err))
	}

	metadataJSON, err := metadatautil.YAMLToJSON(metadataYAML)
	if err != nil {
		return nil, errors.E(op, fmt.Errorf("parsing local yaml metadata as json: %w", err))
	}

	return bytes.NewReader(metadataJSON), nil
}

func (m *metadataModeYAMLHandler) Diff(p *ProjectMetadata) (io.Reader, error) {
	var op errors.Op = "metadata.metadataModeYAMLHandler.Diff"

	r, err := diff(p)
	if err != nil {
		return nil, errors.E(op, err)
	}

	return r, nil
}

func (m *metadataModeYAMLHandler) Export(p *ProjectMetadata) (io.Reader, error) {
	var op errors.Op = "metadata.metadataModeYAMLHandler.Export"

View on GitHub (pinned to 724551b9ae)

Solutions

1. Lint the file: `yamllint metadata.yaml` or `hasura metadata diff` to surface the parse error position
2. Fix tabs→spaces, indentation, and remove conflict markers/duplicates
3. Re-export a known-good file (`hasura metadata export`) and reapply your changes incrementally
4. Keep CLI and server versions aligned

Example fix

# before (metadata.yaml)
version:	3   # tab + bad structure

# after
version: 3

var v any
if err := yaml.Unmarshal(raw, &v); err != nil {
    return fmt.Errorf("metadata.yaml invalid: %w", err)
}

if _, err := h.Parse(&p); err != nil {
    if strings.Contains(err.Error(), "parsing local yaml metadata as json") {
        // yamllint metadata.yaml; fix tabs/duplicate keys, then retry
    }
}

When it happens

Trigger: Running a metadata command in YAML mode where metadata.yaml has a YAML syntax error (tabs, bad indentation, unclosed quotes) or duplicate keys/complex keys that can't map to JSON.

Common situations: Hand-edited metadata.yaml with tab indentation or merge conflict markers; duplicate top-level keys; pasting JSON-with-comments into a .yaml file; version skew where metadata schema keys changed.

Related errors

• parsing metadata to yaml: %w
• reading server metadata: %w
• parsing project metadata to json failed: %w
• error fetching config from server: %w
• error fetching server config: %v

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