hasura/graphql-engine · warning · errors.Error

validating global config file failed: %w

Error message

validating global config file failed: %w

What it means

After successfully reading the existing config file, validateKeys() found keys that are unknown/not allowed (or required keys missing). The config parses fine but contains entries the current CLI version does not recognize, typically from an older/newer version or manual additions.

Source

Thrown at cli/global_config.go:187

		// also show a notice about telemetry
		ec.Logger.Info(TelemetryNotice)
	} else if stderrors.Is(err, fs.ErrExist) || err == nil {
		// file exists, verify contents
		ec.Logger.Debug("global config file exists, verifying contents")

		// initialize the config object
		gc := rawGlobalConfig{}

		err := gc.read(ec.GlobalConfigFile)
		if err != nil {
			return errors.E(op, fmt.Errorf("reading global config file failed: %w", err))
		}

		// validate keys
		err = gc.validateKeys()
		if err != nil {
			return errors.E(op, fmt.Errorf("validating global config file failed: %w", err))
		}

		// write the file if there are any changes
		if gc.shoudlWrite {
			err := gc.write(ec.GlobalConfigFile)
			if err != nil {
				return errors.E(op, fmt.Errorf("writing global config file failed: %w", err))
			}

			ec.Logger.Debugf(
				"global config file written at '%s' with content '%+#v'",
				ec.GlobalConfigFile,
				gc,
			)
		}
	}

	err = ec.readGlobalConfig()

View on GitHub (pinned to 724551b9ae)

Solutions

1. Remove the unrecognized keys reported in the wrapped error message
2. Upgrade the CLI to the version that understands those keys
3. Regenerate the file: back it up, delete it, let the CLI recreate a valid one
4. Keep version-specific configs in separate GlobalConfigDir trees

Example fix

# before (config.yaml)
uuid: ...
cli_environment: dev
my_custom_key: true   # unknown key
# after
uuid: ...
cli_environment: dev

b, err := os.ReadFile(ec.GlobalConfigFile)
if err == nil {
    var m map[string]any
    _ = yaml.Unmarshal(b, &m)
    known := map[string]bool{"uuid": true, "cli_environment": true}
    for k := range m {
        if !known[k] {
            return fmt.Errorf("unknown key %q in config; remove it", k)
        }
    }
}

func hasOnlyKnownKeys(path string, known map[string]bool) bool {
    b, err := os.ReadFile(path)
    if err != nil {
        return false
    }
    var m map[string]any
    if yaml.Unmarshal(b, &m) != nil {
        return false
    }
    for k := range m {
        if !known[k] {
            return false
        }
    }
    return true
}

if err := ec.Prepare(ctx); err != nil {
    if strings.Contains(err.Error(), "validating global config file failed") {
        bak := ec.GlobalConfigFile + ".bak"
        _ = os.Rename(ec.GlobalConfigFile, bak)
        return ec.Prepare(ctx)
    }
    return err
}

When it happens

Trigger: Adding a custom key to config.yaml that is not in the known-keys allowlist, downgrading the CLI after a newer version wrote new keys, or sharing a config between CLI versions.

Common situations: Version skew (config written by newer CLI, executed by older one), copy-pasted config snippets from docs of a different version, or leftover experimental keys.

Related errors

• cannot validate new config: %w
• did not find required directory. use 'init'?: %w
• '%s' is not a directory: %w
• cannot validate directory '%s': [%s] not found
• read file: %w

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