hasura/graphql-engine · error

cannot upgrade: unsupported server version %v, config V3 is

Error message

cannot upgrade: unsupported server version %v, config V3 is supported only on server with metadata version >= 3

What it means

Thrown by scripts.UpdateProjectV3 when the connected Hasura server does not advertise metadata API version 3 (opts.EC.HasMetadataV3 is false). Config V3 projects require a server with metadata version >= 3, so the upgrade is refused before touching any files.

Source

Thrown at cli/internal/scripts/update-project-v3.go:57

	/* New flow
		Config V2 -> Config V3
		- Warn user about creating a backup
		- Ask user for the name of database to migrate to
	  	- copy state from hdb_tables to catalog state
		- Move current migration directories to a new source directory
		- Move seeds belonging to the source to a new directory
		- Update config file and version
	*/

	// pre checks
	if opts.EC.Config.Version != cli.V2 && !opts.MoveStateOnly {
		return errors.E(op, "project should be using config V2 to be able to update to V3")
	}

	if !opts.EC.HasMetadataV3 {
		return errors.E(
			op,
			fmt.Errorf(
				"cannot upgrade: unsupported server version %v, config V3 is supported only on server with metadata version >= 3",
				opts.EC.Version.Server,
			),
		)
	}

	r, err := opts.EC.APIClient.V1Metadata.GetInconsistentMetadata()
	if err != nil {
		return errors.E(op, fmt.Errorf("determining server metadata inconsistency: %w", err))
	}

	if !r.IsConsistent {
		return errors.E(op, "cannot continue: metadata is inconsistent on the server")
	}

	opts.Logger.Infof(
		"The upgrade process will make some changes to your project directory, It is advised to create a backup project directory before continuing",
	)

View on GitHub (pinned to 724551b9ae)

Solutions

1. Upgrade the Hasura server to a version with metadata V3 support (>= 2.13.0, ideally latest v2.x) and retry
2. Verify the CLI is pointed at the intended server: check the endpoint in config.yaml / HASURA_GRAPHQL_ENDPOINT env
3. If the server cannot be upgraded, keep the project on config V2

Example fix

// config.yaml
# before (targeting old server, v2 config):
version: 2
endpoint: https://old-hasura.example.com

# after: upgrade server >= 2.13, then re-run
# hasura scripts update-project-v3
version: 3
endpoint: https://hasura-v213.example.com

// before invoking UpdateProjectV3:
if !ec.HasMetadataV3 {
	return fmt.Errorf("server %s lacks metadata V3; upgrade server first", ec.Version.Server)
}

When it happens

Trigger: Running the V2->V3 project upgrade (hasura scripts update-project-v3) against a Hasura server older than v2.13-ish / one whose version_info.metadata_object_format does not report 3.

Common situations: Pointing the CLI at an older self-hosted Hasura (e.g. v2.9-2.12) or a stale CE deployment while trying to use the newer config V3 layout; env var HASURA_GRAPHQL_ENDPOINT pointing at the wrong environment.

Related errors

• cannot determine name of database for which current migratio
• determining server metadata inconsistency: %w
• getting list of migrations to move: %w
• getting list of seed files to move: %w
• failed to get the matching platform for plugin %s: %w

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