hasura/graphql-engine · error

metadata diff for config %d not supported

Error message

metadata diff for config %d not supported

What it means

The metadata diff command only knows how to build metadata for specific project config versions; if o.EC.Config.Version is not one of the handled values, it falls through to this error. It indicates the project's config.yaml version is not supported by this CLI build's diff logic.

Source

Thrown at cli/commands/metadata_diff.go:127

	)

	return metadataDiffCmd
}

func (o *MetadataDiffOptions) Run() error {
	var op errors.Op = "commands.MetadataDiffOptions.Run"

	if o.EC.Config.Version >= cli.V2 && o.EC.MetadataDir != "" {
		err := getMetadataModeHandler(o.EC.MetadataMode).Diff(o)
		if err != nil {
			return errors.E(op, err)
		}

		return nil
	} else {
		return errors.E(
			op,
			fmt.Errorf("metadata diff for config %d not supported", o.EC.Config.Version),
		)
	}
}

type DiffType string

const (
	DifftypeUnifiedJSON DiffType = "unified-json"
	DifftypeUnifiedYAML DiffType = "unified-yaml"
	DifftypeYAML        DiffType = "yaml"
	DifftypeJSON        DiffType = "json"
)

const zeroDifferencesFound = "zero differences found"

type printGeneratedMetadataFileDiffOpts struct {
	projectMetadataHandler *projectmetadata.Handler
	// actual directory paths to project directory

View on GitHub (pinned to 724551b9ae)

Solutions

1. Update the CLI to a version matching your project (v3 projects need a recent CLI): hasura update-cli
2. Or set the config version in config.yaml to a version your CLI supports and re-export metadata to match
3. Verify with `hasura version` and compare against the project's Hasura server version

Example fix

# config.yaml (project needs v3)
version: 3
# upgrade CLI instead of downgrading project:
# hasura update-cli

# Shell: assert config version supported by this CLI
V=$(grep -E '^version:' config.yaml | awk '{print $2}')
[ "$V" = "3" ] || { echo "config version $V not supported by this CLI"; exit 1; }

// Go
func supportedConfigVersion(v config.Version) bool {
  return v == config.V1 || v == config.V2 || v == config.V3
}

When it happens

Trigger: Running `hasura metadata diff` in a project whose config.yaml has a Version the diff command does not handle (e.g. a v3 project with an older CLI that only diffs v1/v2 configs, or a newer config version than the CLI knows).

Common situations: Project created with a newer Hasura CLI then opened with an older one, manually bumped config version in config.yaml, or CI using a pinned outdated CLI image on a modern project.

Related errors

• metadata diff doesn't support difftype %s
• cannot unmarshal local metadata to json: %w
• cannot unmarshal server metadata to json: %w
• metadata diff only works with folder but got file %s
• cannot convert yaml to json: %w

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