hasura/graphql-engine · error

parsing project metadata to json failed: %w

Error message

parsing project metadata to json failed: %w

What it means

The directory-mode metadata handler builds project metadata from metadata/ directories (tables.yaml, etc.) via BuildJSONMetadata; any failure is wrapped as 'parsing project metadata to json failed'. Root causes are usually invalid YAML in a metadata file or missing/inconsistent referenced objects.

Source

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

		b := new(bytes.Buffer)
		if err := json.NewEncoder(b).Encode(replaceMetadataResponse); err != nil {
			return nil, errors.E(op, fmt.Errorf("encoding json response from server: %w", err))
		}

		return b, nil
	}

	return nil, nil
}

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

	metadataHandler := projectmetadata.NewHandlerFromEC(p.ec)

	jsonMetadata, err := metadataHandler.BuildJSONMetadata()
	if err != nil {
		return nil, errors.E(op, fmt.Errorf("parsing project metadata to json failed: %w", err))
	}

	return bytes.NewReader(jsonMetadata), nil
}

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

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

	return r, nil
}

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

View on GitHub (pinned to 724551b9ae)

Solutions

1. Run `hasura metadata diff` or a YAML linter over each file in the metadata directory to find the syntax error
2. Fix indentation (spaces not tabs) and resolve merge conflict markers
3. If unsure, re-export clean metadata: `hasura metadata export` (or fetch from server) and diff against your files
4. Keep server and CLI versions aligned so metadata schemas match

Example fix

# before (metadata/tables.yaml, tab-indented)
table:
	name: users

# after
table:
  name: users

// Lint all metadata YAML before running metadata commands
err := filepath.Walk(metadataDir, func(p string, _ os.FileInfo, err error) error {
    if err != nil || (!strings.HasSuffix(p, ".yaml") && !strings.HasSuffix(p, ".yml")) { return err }
    b, _ := os.ReadFile(p)
    var v any
    if yerr := yaml.Unmarshal(b, &v); yerr != nil { return fmt.Errorf("%s: %w", p, yerr) }
    return nil
})

if r, err := h.Parse(&p); err != nil {
    if strings.Contains(err.Error(), "parsing project metadata") {
        // run yamllint over metadata/ and fix the flagged file
    }
}

When it happens

Trigger: Running metadata operations (apply/export/diff/inconsistency) with metadata in directory format (`metadata_directory: metadata`) when one of the YAML files fails to parse or references malformed structures during BuildJSONMetadata.

Common situations: Hand-editing metadata/tables.yaml with invalid YAML; merge conflicts in metadata files; metadata files referencing dropped sources/tables; tabs or bad indentation in YAML.

Related errors

• parsing local yaml metadata as json: %w
• error fetching config from server: %w
• error fetching server config: %v
• 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/d6d0d318d79be1b4. Report an issue: GitHub.