hasura/graphql-engine · error

metadata diff doesn't support difftype %s

Error message

metadata diff doesn't support difftype %s

What it means

A cobra flag-validation error for `hasura metadata diff`: the --type-of-diff flag value is checked against the supported list and any value not present causes this error naming the offending difftype. Supported values include plain human, json, unified-yaml, unified-json (per the diffTypes slice). Pure input validation; nothing is fetched from the server before this fires.

Source

Thrown at cli/commands/metadata_diff.go:75

		PreRunE: func(cmd *cobra.Command, args []string) error {
			op := genOpName(cmd, "PreRunE")

			if len(opts.DiffType) > 0 {
				optsDiffType := DiffType(opts.DiffType)

				diffTypes := []DiffType{
					DifftypeJSON,
					DifftypeYAML,
					DifftypeUnifiedJSON,
					DifftypeUnifiedYAML,
				}
				if slices.Contains(diffTypes, optsDiffType) {
					return nil
				}

				return errors.E(
					op,
					fmt.Errorf("metadata diff doesn't support difftype %s", optsDiffType),
				)
			}

			return nil
		},
		RunE: func(cmd *cobra.Command, args []string) error {
			op := genOpName(cmd, "RunE")
			opts.Args = args

			opts.DisableColor = ec.NoColor

			err := opts.Run()
			if err != nil {
				return errors.E(op, err)
			}

			return nil
		},

View on GitHub (pinned to 724551b9ae)

Solutions

1. Use a supported difftype: run `hasura metadata diff --help` to list them for your version
2. Check spelling and separators (hyphens not underscores, exact case)
3. Upgrade/downgrade the CLI to the version your scripts were written for

Example fix

# before
hasura metadata diff --type-of-diff unified_json
# after
hasura metadata diff --type-of-diff unified-json

# Shell: enforce supported difftypes in wrappers
DIFFTYPE="$1"
case "$DIFFTYPE" in
  human|json|unified-yaml|unified-json) ;;
  *) echo "unsupported difftype: $DIFFTYPE"; exit 2 ;;
esac
hasura metadata diff --type-of-diff "$DIFFTYPE"

// Go
func isSupportedDiffType(t DiffType, supported []DiffType) bool {
  return slices.Contains(supported, t)
}

When it happens

Trigger: Passing an unsupported value to --type-of-diff, e.g. `hasura metadata diff --type-of-diff xml` or a misspelling like 'unified_yaml' (underscore instead of hyphen) — exact string membership in diffTypes is required.

Common situations: Typos, using underscores instead of hyphens, scripts written against a different CLI version with renamed diff types, or forgetting that the value is case-sensitive.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• metadata diff only works with folder but got file %s
• output format '%v' is not supported. supported formats: %v,
• error while parsing the endpoint :%w
• failed to get version from server: %w
• cannot read config from file/env: %w

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