hasura/graphql-engine · error

metadata diff only works with folder but got file %s

Error message

metadata diff only works with folder but got file %s

What it means

checkDir validates that a path passed to metadata diff is a directory; if os.Stat succeeds but the path is a regular file, this error is returned. The diff command needs a directory containing multiple metadata files, not a single file.

Source

Thrown at cli/commands/metadata_diff.go:286

			fmt.Fprintf(to, "%s\n", ansi.Color(text, "red"))
		case difflib.Common:
			fmt.Fprintf(to, "%s\n", text)
		}
	}
}

func checkDir(path string) error {
	var op errors.Op = "commands.checkDir"

	file, err := os.Stat(path)
	if err != nil {
		return errors.E(op, err)
	}

	if !file.IsDir() {
		return errors.E(
			op,
			fmt.Errorf("metadata diff only works with folder but got file %s", path),
		)
	}

	return nil
}

func convertYamlToJsonWithIndent(yamlByt []byte) ([]byte, error) {
	var op errors.Op = "commands.convertYamlToJsonWithIndent"

	jsonByt, err := metadatautil.YAMLToJSON(yamlByt)
	if err != nil {
		return nil, errors.E(op, fmt.Errorf("cannot convert yaml to json: %w", err))
	}

	var jsonBuf bytes.Buffer

	err = json.Indent(&jsonBuf, jsonByt, "", "  ")
	if err != nil {

View on GitHub (pinned to 724551b9ae)

Solutions

1. Pass the metadata directories, not individual files: hasura metadata diff ./metadata ./other-project/metadata
2. Verify with ls -d <path> that each argument is a directory
3. If comparing a single file, diff it manually or restructure to compare whole directories

Example fix

# before
hasura metadata diff metadata/tables.yaml other/metadata/tables.yaml
# after
hasura metadata diff metadata other/metadata

# Shell: ensure both args are directories
for d in "$1" "$2"; do [ -d "$d" ] || { echo "not a directory: $d"; exit 1; }; done
hasura metadata diff "$1" "$2"

// Go
func isDirectory(path string) bool {
  info, err := os.Stat(path)
  return err == nil && info.IsDir()
}

When it happens

Trigger: Passing a file path where a directory is expected: `hasura metadata diff ./metadata/tables.yaml ./other/metadata` — the first argument must be a directory. Also triggered by symlink targets that resolve to files.

Common situations: Assuming diff takes individual metadata files like tables.yaml instead of the whole metadata directory, tab-completing to a file inside the directory, or scripts hardcoding a file path.

Related errors

• metadata diff doesn't support difftype %s
• unable to create directory: %w
• generating docs failed: %w
• error getting current working directory: %w
• directory '%s' already exists

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