hasura/graphql-engine · error · errors.Error

setup global config object: %w

Error message

setup global config object: %w

What it means

While creating a brand-new global config file, validateKeys() on the freshly constructed empty rawGlobalConfig returned an error. This indicates the in-code set of expected/allowed keys is internally inconsistent (e.g. defaults defined for keys that are not in the known-keys list) rather than any user input problem — the object is empty at this point.

Source

Thrown at cli/global_config.go:155

		ec.GlobalConfigFile = filepath.Join(ec.GlobalConfigDir, GlobalConfigFileName)
		ec.Logger.Debugf("global config file set as '%s'", ec.GlobalConfigFile)
	}

	// check if the global config file exist
	_, err = os.Stat(ec.GlobalConfigFile)
	if stderrors.Is(err, fs.ErrNotExist) {
		// file does not exist, teat as first run and create it
		ec.Logger.Debug(
			"global config file does not exist, this could be the first run, creating it...",
		)

		// create an empty config object
		gc := &rawGlobalConfig{}

		// populate the keys
		err := gc.validateKeys()
		if err != nil {
			return errors.E(op, fmt.Errorf("setup global config object: %w", err))
		}

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

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

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

View on GitHub (pinned to 724551b9ae)

Solutions

1. Upgrade or pin to a CLI version without the key-validation mismatch (this is effectively an internal bug)
2. If building from source, ensure every key with a default appears in the allowed-keys set used by validateKeys
3. Report the issue upstream with the CLI version
4. As a workaround, pre-create a valid config file so the code takes the read path instead of the create path

if err := ec.Prepare(ctx); err != nil {
    if strings.Contains(err.Error(), "setup global config object") {
        // internal key-validation bug: pin a known-good CLI version
        log.Fatal("known bug in this CLI version; upgrade the CLI")
    }
    return err
}

When it happens

Trigger: A version of the CLI where a new config key was added to rawGlobalConfig/defaults but not registered in the known keys map, so validateKeys rejects the empty object on first-run initialization.

Common situations: Upgrading to a release with a key-validation regression, running a dev build mid-refactor, or a fork where keys were edited without updating the validation list.

Related errors

• read file: %w
• parse file %w
• marshal file: %w
• write file: %w
• cannot get home directory: %w

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