hasura/graphql-engine · error

parsing metadata as json: %w

Error message

parsing metadata as json: %w

What it means

After optionally converting YAML, the CLI unmarshals the metadata bytes as JSON into an any. This error (marked errors.KindBadInput) means the metadata content is not valid JSON — malformed syntax, a BOM, trailing garbage, or non-text bytes. For YAML mode it can also mean YAMLToJSON produced content that still is not valid JSON, though usually the YAML step catches that first.

Source

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

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

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

	var metadata any

	err = json.Unmarshal(localMetadataBytes, &metadata)
	if err != nil {
		return nil, errors.E(
			op,
			errors.KindBadInput,
			fmt.Errorf("parsing metadata as json: %w", err),
		)
	}

	if p.ec.Config.Version == cli.V2 {
		r, err := cli.GetCommonMetadataOps(p.ec).
			ReplaceMetadata(bytes.NewReader(localMetadataBytes))
		if err != nil {
			return nil, errors.E(op, err)
		}

		return r, nil
	}

	r, err := p.ec.APIClient.V1Metadata.V2ReplaceMetadata(hasura.V2ReplaceMetadataArgs{
		AllowInconsistentMetadata: true,
		Metadata:                  metadata,
	})
	if err != nil {

View on GitHub (pinned to 724551b9ae)

Solutions

1. Validate with `jq . metadata/metadata.json` (or `python -m json.tool`) to locate the exact syntax error
2. Remove comments, trailing commas, and ensure the file is a single valid JSON value
3. Re-export metadata to get a known-good file: `hasura metadata export`
4. Confirm the metadata mode matches the file format (YAML file with YAML mode, JSON with JSON)

Example fix

// before (metadata.json)
{
  "version": 3, // v3  <- comments invalid in JSON
}
// after
{
  "version": 3
}

import "encoding/json"
var v any
if err := json.Unmarshal(raw, &v); err != nil {
    return fmt.Errorf("metadata file is not valid JSON: %w", err)
}

When it happens

Trigger: Calling Apply with a metadata file whose bytes fail json.Unmarshal: trailing commas, single quotes, comments (invalid in JSON), a UTF-8 BOM, or an empty/corrupted file. This is classified KindBadInput, i.e. user-provided input is at fault.

Common situations: Hand-editing metadata.json with JSON-incompatible syntax (comments, trailing commas); editor saving with BOM; truncated file from an interrupted export; applying a YAML file while running in JSON mode.

Related errors

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

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