hasura/graphql-engine · error

reading metadata file: %w

Error message

reading metadata file: %w

What it means

The JSON-mode metadata handler reads the file at ec.MetadataFile (default metadata.json) with os.ReadFile; any IO failure becomes 'reading metadata file'. Typically the file doesn't exist (metadata is in YAML/directory format) or isn't readable.

Source

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

type metadataModeJSONHandler struct{}

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

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

	return r, nil
}

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

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

	return bytes.NewReader(metadataJSON), nil
}

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

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

	return r, nil
}

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

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check that the file in `metadata_file` (config.yaml) exists relative to the project root
2. If your metadata is YAML, set the correct format/filename in config.yaml (metadata_file: metadata.yaml)
3. Create or restore metadata.json (git checkout or `hasura metadata export` after switching format)
4. Verify read permissions

Example fix

# before (config.yaml)
metadata_file: metadata.json   # file doesn't exist

# after
metadata_file: metadata.yaml

if _, err := os.Stat(ec.MetadataFile); err != nil {
    return fmt.Errorf("metadata file %s missing; run hasura metadata export", ec.MetadataFile)
}

if _, err := h.Parse(&p); err != nil {
    if strings.Contains(err.Error(), "reading metadata file") {
        // fix metadata_file in config.yaml or restore the file
    }
}

When it happens

Trigger: Running a metadata command when the CLI is configured for JSON metadata format but metadata.json is absent — e.g. project uses metadata.yaml while config expects JSON — or the file lacks read permission.

Common situations: Fresh clone where metadata.json is gitignored; project switched to metadata.yaml but config still points at JSON; wrong working directory; file deleted or renamed.

Related errors

• error fetching config from server: %w
• error fetching server config: %v
• cannot write metadata directory: %w
• cannot create metadata files: %w
• reading metadata file: %w

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