hasura/graphql-engine · error

reading metadata file: %w

Error message

reading metadata file: %w

What it means

The `metadata apply` command begins by reading the local metadata file (o.EC.MetadataFile) with os.ReadFile. This error means the local file could not be read — it does not exist, is not readable, or the configured path is wrong. It is purely a local filesystem error, before any server interaction.

Source

Thrown at cli/commands/metadata_handlers.go:354

	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
	)

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

	if o.DryRun {
		if len(o.rawOutput) == 0 {
			o.rawOutput = string(rawOutputFormatJSON)
		}

		err := writeByOutputFormat(o.EC.Stdout, localMetadataBytes, rawOutputFormat(o.rawOutput))
		if err != nil {
			return errors.E(op, fmt.Errorf("displaying metadata failed: %w", err))
		}

		return nil
	}

	if mode == cli.MetadataModeYAML {
		localMetadataBytes, err = metadatautil.YAMLToJSON(localMetadataBytes)
		if err != nil {

View on GitHub (pinned to 724551b9ae)

Solutions

1. Confirm the metadata file path in your config and verify the file exists at that exact path (ls it from the CLI's working directory)
2. If the file is missing, run `metadata export` to generate it or restore it from version control
3. Fix read permissions (chmod +r) if the file exists but is unreadable
4. Run the CLI from the project root so relative metadata file paths resolve correctly

Example fix

# before
hasura metadata apply  # reading metadata file: ... no such file or directory
# after
ls metadata.json  # confirm location, fix config path, then:
hasura metadata apply

if _, err := os.Stat(ec.MetadataFile); err != nil {
  if os.IsNotExist(err) {
    return errors.New("metadata file missing — run `metadata export` first")
  }
  return fmt.Errorf("metadata file unreadable: %w", err)
}

if err := apply(o, mode); err != nil {
  if strings.Contains(err.Error(), "reading metadata file") {
    // create or fix the metadata file path, then retry
  }
}

When it happens

Trigger: Running `metadata apply` when the configured metadata file does not exist at the resolved path, has no read permission, or the path points to a directory.

Common situations: Fresh clone where metadata file is not committed or named differently than config expects; config specifying an absolute path valid on another machine; running the CLI from the wrong working directory so a relative path does not resolve; file permissions locked down (chmod 000) or owned by another user.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• writing metadata to file: %w
• reading local metadata: %w
• error building project metadata: %w
• exporting metadata from server: %w
• reading metadata from response: %w

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