{"record":{"id":"6599f2da293bb0eb","repo":"hasura/graphql-engine","slug":"validating-global-config-file-failed-w","errorCode":null,"errorMessage":"validating global config file failed: %w","messagePattern":"validating global config file failed: %w","errorType":"exception","errorClass":"errors.Error","httpStatus":null,"severity":"warning","filePath":"cli/global_config.go","lineNumber":187,"sourceCode":"\n\t\t// also show a notice about telemetry\n\t\tec.Logger.Info(TelemetryNotice)\n\t} else if stderrors.Is(err, fs.ErrExist) || err == nil {\n\t\t// file exists, verify contents\n\t\tec.Logger.Debug(\"global config file exists, verifying contents\")\n\n\t\t// initialize the config object\n\t\tgc := rawGlobalConfig{}\n\n\t\terr := gc.read(ec.GlobalConfigFile)\n\t\tif err != nil {\n\t\t\treturn errors.E(op, fmt.Errorf(\"reading global config file failed: %w\", err))\n\t\t}\n\n\t\t// validate keys\n\t\terr = gc.validateKeys()\n\t\tif err != nil {\n\t\t\treturn errors.E(op, fmt.Errorf(\"validating global config file failed: %w\", err))\n\t\t}\n\n\t\t// write the file if there are any changes\n\t\tif gc.shoudlWrite {\n\t\t\terr := gc.write(ec.GlobalConfigFile)\n\t\t\tif err != nil {\n\t\t\t\treturn errors.E(op, fmt.Errorf(\"writing global config file failed: %w\", err))\n\t\t\t}\n\n\t\t\tec.Logger.Debugf(\n\t\t\t\t\"global config file written at '%s' with content '%+#v'\",\n\t\t\t\tec.GlobalConfigFile,\n\t\t\t\tgc,\n\t\t\t)\n\t\t}\n\t}\n\n\terr = ec.readGlobalConfig()","sourceCodeStart":169,"sourceCodeEnd":205,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/cli/global_config.go#L169-L205","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove the unrecognized keys reported in the wrapped error message","Upgrade the CLI to the version that understands those keys","Regenerate the file: back it up, delete it, let the CLI recreate a valid one","Keep version-specific configs in separate GlobalConfigDir trees"],"exampleFix":"# before (config.yaml)\nuuid: ...\ncli_environment: dev\nmy_custom_key: true   # unknown key\n# after\nuuid: ...\ncli_environment: dev","handlingStrategy":"validation","validationCode":"b, err := os.ReadFile(ec.GlobalConfigFile)\nif err == nil {\n    var m map[string]any\n    _ = yaml.Unmarshal(b, &m)\n    known := map[string]bool{\"uuid\": true, \"cli_environment\": true}\n    for k := range m {\n        if !known[k] {\n            return fmt.Errorf(\"unknown key %q in config; remove it\", k)\n        }\n    }\n}","typeGuard":"func hasOnlyKnownKeys(path string, known map[string]bool) bool {\n    b, err := os.ReadFile(path)\n    if err != nil {\n        return false\n    }\n    var m map[string]any\n    if yaml.Unmarshal(b, &m) != nil {\n        return false\n    }\n    for k := range m {\n        if !known[k] {\n            return false\n        }\n    }\n    return true\n}","tryCatchPattern":"if err := ec.Prepare(ctx); err != nil {\n    if strings.Contains(err.Error(), \"validating global config file failed\") {\n        bak := ec.GlobalConfigFile + \".bak\"\n        _ = os.Rename(ec.GlobalConfigFile, bak)\n        return ec.Prepare(ctx)\n    }\n    return err\n}","preventionTips":["Keep only documented keys in the config file","Match CLI and config versions; use separate config dirs per version","Regenerate config after upgrades instead of accumulating keys"],"tags":["go","config","validation","version-skew"],"backgroundTag":"config-schema-validation-failed","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}