{"record":{"id":"dc2bd5551e5e2494","repo":"derailed/k9s","slug":"k9s-config-file-q-load-failed-w","errorCode":null,"errorMessage":"k9s config file %q load failed:\n%w","messagePattern":"k9s config file %q load failed:\n%w","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"internal/config/config.go","lineNumber":283,"sourceCode":"\nfunc (c *Config) Merge(c1 *Config) {\n\tc.K9s.Merge(c1.K9s)\n}\n\n// Load loads K9s configuration from file.\nfunc (c *Config) Load(path string, force bool) error {\n\tif _, err := os.Stat(path); errors.Is(err, fs.ErrNotExist) {\n\t\tif err := c.Save(force); err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\tbb, err := os.ReadFile(path)\n\tif err != nil {\n\t\treturn err\n\t}\n\tvar errs error\n\tif err := data.JSONValidator.Validate(json.K9sSchema, bb); err != nil {\n\t\terrs = errors.Join(errs, fmt.Errorf(\"k9s config file %q load failed:\\n%w\", path, err))\n\t}\n\n\tvar cfg Config\n\tif err := yaml.Unmarshal(bb, &cfg); err != nil {\n\t\terrs = errors.Join(errs, fmt.Errorf(\"main config.yaml load failed: %w\", err))\n\t}\n\tc.Merge(&cfg)\n\n\treturn errs\n}\n\n// Save configuration to disk.\nfunc (c *Config) Save(force bool) error {\n\tcontextName := c.K9s.ActiveContextName()\n\t// Skip saving if no context is configured\n\tif contextName == \"\" {\n\t\tslog.Debug(\"No context configured, skipping config save\")\n\t\treturn nil","sourceCodeStart":265,"sourceCodeEnd":301,"githubUrl":"https://github.com/derailed/k9s/blob/2d3ccc6ba2ce98c3781bfc441bb3e884f072774f/internal/config/config.go#L265-L301","documentation":"Returned from Config.Load (internal/config/config.go:283) when the main k9s config file fails validation against the K9s JSON schema (data.JSONValidator.Validate with json.K9sSchema). Typically means unknown keys, misspelled keys, or values that changed shape between k9s versions. Errors are joined (errors.Join) — the schema error may arrive together with the unmarshal error from line 288 — and notably Load still merges the parsed config before returning, so the error is advisory: partial config is in effect.","triggerScenarios":"Upgrading k9s while the old config.yml contains keys removed from the new schema (or vice versa: a newer config opened by an older k9s); hand-editing with typo'd key names like 'refreshRate' vs 'refreshrate'; structurally valid YAML that violates the schema.","commonSituations":"k9s major-version upgrades; dotfiles synced across machines running different k9s versions; copy-pasted config snippets from blog posts targeting a different version.","solutions":["Read the validator detail in the message — it names the offending key/field and the schema path","Rename or delete the flagged keys per the current version's config schema","After a version upgrade, back up and let k9s regenerate a fresh config, then re-apply your customizations","Keep one k9s version across machines if you sync the config file"],"exampleFix":"# before: config.yml after upgrade\nui:\n  skin: monokai      # removed key in new schema -> validation error\n\n# after: check schema, use current key\nui:\n  skin: monokai\n  # e.g. renamed to: activeSkin: monokai  (per validator message)","handlingStrategy":"try-catch","validationCode":"// Pre-validate the config against the shipped schema before k9s loads it:\nfunc configSchemaOK(path string) bool {\n\tbb, err := os.ReadFile(path)\n\tif err != nil {\n\t\treturn false\n\t}\n\treturn data.JSONValidator.Validate(json.K9sSchema, bb) == nil\n}","typeGuard":null,"tryCatchPattern":"if err := cfg.Load(path, force); err != nil {\n\t// Load joins schema + unmarshal errors; split them:\n\tvar joined interface{ Unwrap() []error }\n\tif errors.As(err, &joined) {\n\t\tfor _, e := range joined.Unwrap() {\n\t\t\tif strings.Contains(e.Error(), \"load failed\") {\n\t\t\t\t// schema/yaml drift: warn, config still partially applied\n\t\t\t} else {\n\t\t\t\t// harder failure: inspect\n\t\t\t}\n\t\t}\n\t}\n}","preventionTips":["Back up config.yml before every k9s upgrade (cp config.yml config.yml.$(k9s version))","After upgrading, launch once, fix keys the validator names, then customize","Do not sync config.yml between machines running different k9s versions"],"tags":["k9s","config","schema","validation","yaml","upgrade"],"backgroundTag":null,"analyzedSha":"2d3ccc6ba2ce98c3781bfc441bb3e884f072774f","analyzedAt":"2026-08-15T16:09:14.432Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}