hasura/graphql-engine · error · errors.Error

reading global config file failed: %w

Error message

reading global config file failed: %w

What it means

An existing global config file was found, but gc.read(ec.GlobalConfigFile) failed to parse it. This is a malformed config file: invalid YAML/JSON syntax, wrong types for fields, or a file that cannot be opened (permission/chmod). The wrapped error usually carries the parse position.

Source

Thrown at cli/global_config.go:181

		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
		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,

View on GitHub (pinned to 724551b9ae)

Solutions

1. Validate the file syntax with a YAML/JSON linter and fix the reported line/column
2. Restore from a backup or delete the file to let the CLI regenerate defaults
3. Check for tabs vs spaces if YAML (tabs are illegal for indentation)
4. If types matter, ensure values match expected types (strings quoted when needed)

Example fix

# before (config.yaml)
uuid: my-uuid
cli_environment: dev
  extra_tab: oops
# after
uuid: my-uuid
cli_environment: dev

if b, err := os.ReadFile(ec.GlobalConfigFile); err == nil {
    var probe map[string]any
    if err := yaml.Unmarshal(b, &probe); err != nil {
        return fmt.Errorf("config file is malformed, fix or delete %s: %w", ec.GlobalConfigFile, err)
    }
}

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

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

When it happens

Trigger: Manually editing ~/.<app>/config.<ext> and introducing a syntax error (tab indentation in YAML, missing quote, trailing comma in JSON), or another tool overwriting the file with garbage.

Common situations: Hand-edited config after following online tutorials, secrets-injection tools mangling YAML, config managed by Helm/sed substitutions producing invalid syntax, or a truncated file from a crashed write.

Related errors

• parse file %w
• cue extraction error: %w
• cannot unmarshal local metadata to json: %w
• cannot unmarshal server metadata to json: %w
• cannot validate new config: %w

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