hasura/graphql-engine · error

cannot validate new config: %w

Error message

cannot validate new config: %w

What it means

After setting HASURA_GRAPHQL_VERSION=2 and reloading, the CLI re-validates the project config; this fires when ec.Validate() rejects the config under v2 rules. It usually means required v2 settings (metadata_directory, actions endpoints, version) are missing or malformed after the env-var switch.

Source

Thrown at cli/commands/scripts_update_config_v2.go:428

			os.Setenv("HASURA_GRAPHQL_ACTION_KIND", ec.Viper.GetString("actions.kind"))
			os.Setenv(
				"HASURA_GRAPHQL_ACTION_HANDLER_WEBHOOK_BASEURL",
				ec.Viper.GetString("actions.handler_webhook_baseurl"),
			)

			defer func() {
				// unset env
				os.Unsetenv("HASURA_GRAPHQL_VERSION")
				os.Unsetenv("HASURA_GRAPHQL_METADATA_DIRECTORY")
				os.Unsetenv("HASURA_GRAPHQL_ACTION_KIND")
				os.Unsetenv("HASURA_GRAPHQL_ACTION_HANDLER_WEBHOOK_BASEURL")
			}()

			ec.Spin("Reloading config file...")

			err = ec.Validate()
			if err != nil {
				return errors.E(op, fmt.Errorf("cannot validate new config: %w", err))
			}

			defer func() {
				if err != nil {
					os.RemoveAll(ec.MetadataDir)
				}
			}()
			// set codegen to nil, so that it is not exported in yaml
			ec.Config.ActionConfig.Codegen = nil
			// run metadata export
			ec.Spin("Exporting metadata...")

			var files map[string][]byte

			mdHandler := projectmetadata.NewHandlerFromEC(ec)

			files, err = mdHandler.ExportMetadata()
			if err != nil {

View on GitHub (pinned to 724551b9ae)

Solutions

1. Set metadata_directory (and actions.kind, actions.handler_webhook_baseurl if actions are used) in config.yaml before re-running
2. Inspect config.yaml for syntax errors with a YAML linter
3. Ensure no stale HASURA_GRAPHQL_* env vars conflict with the new config
4. Re-run `hasura scripts update-project-v2`

Example fix

# before
metadata_directory:
# after
metadata_directory: metadata

// pre-flight: confirm v2-required keys exist
v := viper.New(); v.SetConfigFile("config.yaml"); _ = v.ReadInConfig()
if v.GetString("metadata_directory") == "" { log.Fatal("set metadata_directory") }

if err := cmd.RunE(cmd, args); err != nil && strings.Contains(err.Error(), "cannot validate new config") {
    // inspect config.yaml, add missing keys, re-run
}

When it happens

Trigger: Running update-project-v2 with no metadata_directory set in config.yaml, missing actions.kind / handler_webhook_baseurl, or a config.yaml that was hand-edited into an invalid shape before the upgrade.

Common situations: Upgrading a v1 project whose config.yaml lacks v2-required fields; stale env vars overriding viper values; YAML syntax errors introduced by manual edits.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

• error getting actions file content: %w
• error in creating action: %w
• framework %s is not found
• starter kit is not available for framework %s
• error in writing config: %w

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