hasura/graphql-engine · error

please upgrade your project to a newer version. use hasura s

Error message

please upgrade your project to a newer version.
use hasura scripts update-project-v2 to upgrade your project to config v2

What it means

CheckIfUpdateToConfigV3IsRequired rejects the operation because the project still uses config version 1 while metadata v3 files are present. Since config v1 is deprecated (from Hasura v1.4), the CLI tells you to first run `hasura scripts update-project-v2`.

Source

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

	}

	cliState.IsStateCopyCompleted = true
	if _, err := statestore.NewCLICatalogState(ec.APIClient.V1Metadata).Set(*cliState); err != nil {
		return errors.E(op, fmt.Errorf("cannot set catalog state: %w", err))
	}

	return nil
}

func CheckIfUpdateToConfigV3IsRequired(ec *cli.ExecutionContext) error {
	var op errors.Op = "scripts.CheckIfUpdateToConfigV3IsRequired"
	// see if an update to config V3 is necessary
	if ec.Config.Version <= cli.V1 && ec.HasMetadataV3 {
		ec.Logger.Info("config v1 is deprecated from v1.4")

		return errors.E(
			op,
			fmt.Errorf(
				"%s",
				"please upgrade your project to a newer version.\nuse "+color.New(color.FgCyan).
					SprintFunc()(
					"hasura scripts update-project-v2",
				)+" to upgrade your project to config v2",
			),
		)
	}

	if ec.Config.Version < cli.V3 && ec.HasMetadataV3 {
		sources, err := metadatautil.GetSources(ec.APIClient.V1Metadata.ExportMetadata)
		if err != nil {
			return errors.E(op, err)
		}

		upgrade := func() error {
			ec.Logger.Info(
				"Looks like you are trying to use hasura with multiple databases, which requires some changes on your project directory\n",

View on GitHub (pinned to 724551b9ae)

Solutions

1. Run `hasura scripts update-project-v2` first to convert config.yaml to version 2
2. Then run `hasura scripts update-project-v3` to finish the migration
3. Alternatively start a fresh project and port metadata/migrations manually

Example fix

# before
hasura scripts update-project-v3
# error: please upgrade your project to a newer version...

# after
hasura scripts update-project-v2
hasura scripts update-project-v3

if ec.Config.Version <= cli.V1 {
    return fmt.Errorf("run `hasura scripts update-project-v2` first")
}

func isConfigV2Plus(v cli.ConfigVersion) bool { return v >= cli.V2 }

if err := scripts.CheckIfUpdateToConfigV3IsRequired(ec); err != nil {
    // surface upgrade-path instruction to the user, run update-project-v2 then retry
}

When it happens

Trigger: Running a v3-era command (e.g. `hasura scripts update-project-v3` or a command calling validateConfigV3Prechecks) on a project whose config.yaml has version: 1 (or no version) and HasMetadataV3 is true.

Common situations: Very old projects created with Hasura < v1.0 being upgraded directly to a modern CLI, skipping the intermediate v2 upgrade step.

Related errors

• pulling latest actions codegen files from internet failed: %
• unable to fetch introspection schema: %w
• error getting actions file content: %w
• error generating codegen for action %s: %w
• error in fetching introspection schema: %w

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