hasura/graphql-engine · error

determining server metadata inconsistency: %w

Error message

determining server metadata inconsistency: %w

What it means

Thrown by scripts.UpdateProjectV3 when the API call V1Metadata.GetInconsistentMetadata fails, i.e. the CLI could not even ask the server whether its metadata is consistent. The %w wraps the HTTP/GraphQL transport or server error. This is a network/server availability problem, not a metadata-consistency verdict (a separate error covers actual inconsistency).

Source

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

	// 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",
	)
	opts.Logger.Warn(`Config V3 is expected to be used with servers >=v2.0.0-alpha.1`)
	opts.Logger.Warn(
		`During the update process CLI uses the server as the source of truth, so make sure your server is upto date`,
	)
	opts.Logger.Warn(`The update process replaces project metadata with metadata on the server`)
	opts.Logger.Infof(
		"Using %s server at %s for update",
		opts.EC.Version.GetServerVersion(),
		opts.EC.Config.Endpoint,

View on GitHub (pinned to 724551b9ae)

Solutions

1. Verify the server is up: curl $HASURA_GRAPHQL_ENDPOINT/healthz
2. Check admin secret / auth env vars are correct for the target environment
3. Fix TLS issues (trust the CA, or use a proper certificate) and retry the upgrade command

// preflight before update-project-v3:
if _, err := ec.APIClient.V1Metadata.GetInconsistentMetadata(); err != nil {
	return fmt.Errorf("server unreachable or auth failed: %w", err)
}

for attempt := 0; attempt < 3; attempt++ {
	err := scripts.UpdateProjectV3(opts)
	if err == nil || !strings.Contains(err.Error(), "determining server metadata inconsistency") {
		break
	}
	time.Sleep(2 * time.Second << attempt) // retry transient transport failures
}

When it happens

Trigger: Running update-project-v3 when the Hasura endpoint is unreachable, returns 5xx, has invalid admin secret/auth, TLS certificate issues, or the server is restarting.

Common situations: Wrong HASURA_GRAPHQL_ENDPOINT, missing/wrong HASURA_GRAPHQL_ADMIN_SECRET, expired auth token, self-signed TLS cert, server pod down during a k8s rollout, local Docker not started.

Related errors

• cannot upgrade: unsupported server version %v, config V3 is
• cannot determine name of database for which current migratio
• getting list of migrations to move: %w
• getting list of seed files to move: %w
• pulling latest actions codegen files from internet failed: %

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