hasura/graphql-engine · error

reading local metadata: %w

Error message

reading local metadata: %w

What it means

`metadata diff` reads the local metadata file (from config) with os.ReadFile to compare it against the server's metadata. This error is a local filesystem failure: the metadata file is missing, unreadable, or the configured path is wrong — it occurs after the server export succeeded.

Source

Thrown at cli/commands/metadata_handlers.go:447

	}

	var serverMetadataBytes []byte

	serverMetadataBytes, err = io.ReadAll(serverMetadata)
	if err != nil {
		return errors.E(op, fmt.Errorf("reading server metadata: %w", err))
	}

	if diffType == DifftypeYAML {
		serverMetadataBytes, err = metadatautil.JSONToYAML(serverMetadataBytes)
		if err != nil {
			return errors.E(op, fmt.Errorf("parsing server metadata as yaml: %w", err))
		}
	}

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

	if err := printMyersDiff(
		string(serverMetadataBytes),
		string(localMetadataBytes),
		"server",
		"project",
		o.Output,
		o.DisableColor,
	); err != nil {
		return errors.E(op, err)
	}

	return nil
}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Run `metadata export` first to create the local metadata file
2. Verify the metadata file path in config and that the file exists and is readable from the CLI's working directory
3. Fix permissions or ownership of the file if needed
4. If you intended to diff a different file, update the config's metadata file setting rather than passing a path argument (diff takes no arguments)

Example fix

# before
hasura metadata diff  # reading local metadata: no such file or directory
# after
hasura metadata export  # creates the file, then
hasura metadata diff

if _, err := os.Stat(ec.MetadataFile); err != nil {
  return errors.New("local metadata file missing — run `metadata export` before diff")
}

if err := diff(o, diffType); err != nil {
  if strings.Contains(err.Error(), "reading local metadata") {
    // export first or fix the metadata file path in config
  }
}

When it happens

Trigger: Running `metadata diff` when the configured metadata file does not exist, lacks read permission, or the path is incorrect/directory — e.g. diffing before ever running `metadata export` in a fresh project.

Common situations: Fresh project where metadata file was never exported or is not committed to the repo; config's metadata file path pointing to a stale location; running from the wrong directory so relative paths fail; file 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

• reading metadata file: %w
• writing metadata to file: %w
• reading server metadata: %w
• parsing server metadata as yaml: %w
• unable to create directory: %w

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