{"record":{"id":"378947bd620b5bd9","repo":"GoogleContainerTools/skaffold","slug":"config-upgrade-err","errorCode":"CONFIG_UPGRADE_ERR","errorMessage":"skaffold cannot auto-upgrade the config from version %s to version %s","messagePattern":"skaffold cannot auto-upgrade the config from version (.+?) to version (.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/skaffold/schema/errors/errors.go","lineNumber":208,"sourceCode":"func ConfigUnknownAPIVersionErr(version string) error {\n\tmsg := fmt.Sprintf(\"unknown skaffold config API version %q\", version)\n\treturn sErrors.NewError(errors.New(msg),\n\t\t&proto.ActionableErr{\n\t\t\tMessage: msg,\n\t\t\tErrCode: proto.StatusCode_CONFIG_UNKNOWN_API_VERSION_ERR,\n\t\t\tSuggestions: []*proto.Suggestion{\n\t\t\t\t{\n\t\t\t\t\tSuggestionCode: proto.SuggestionCode_CONFIG_FIX_API_VERSION,\n\t\t\t\t\tAction:         \"Set the config 'apiVersion' to a known value. Check https://skaffold.dev/docs/references/yaml/ for the list of valid API versions. Otherwise, check that your skaffold version is up-to-date\",\n\t\t\t\t},\n\t\t\t},\n\t\t})\n}\n\n// SkaffoldConfigUpgradeErr specifies that skaffold config needs to be upgraded to the latest version.\nfunc SkaffoldConfigUpgradeErr(currentVersion, targetVersion string) error {\n\tmsg := fmt.Sprintf(\"skaffold cannot auto-upgrade the config from version %s to version %s\", currentVersion, targetVersion)\n\treturn sErrors.NewError(errors.New(msg),\n\t\t&proto.ActionableErr{\n\t\t\tMessage: msg,\n\t\t\tErrCode: proto.StatusCode_CONFIG_UPGRADE_ERR,\n\t\t\tSuggestions: []*proto.Suggestion{\n\t\t\t\t{\n\t\t\t\t\tSuggestionCode: proto.SuggestionCode_CONFIG_FIX_SKAFFOLD_CONFIG_VERSION,\n\t\t\t\t\tAction:         fmt.Sprintf(\"Upgrade skaffold config version to %s manually\", targetVersion),\n\t\t\t\t},\n\t\t\t},\n\t\t})\n}\n","sourceCodeStart":190,"sourceCodeEnd":220,"githubUrl":"https://github.com/GoogleContainerTools/skaffold/blob/a1189de023efc32d4b8e11f395acc678aa555011/pkg/skaffold/schema/errors/errors.go#L190-L220","documentation":"SkaffoldConfigUpgradeErr indicates skaffold found a config whose API version it could not automatically upgrade to the requested target version (no automatic upgrade path exists between the two versions). Code CONFIG_UPGRADE_ERR, suggesting manually fixing the config version.","triggerScenarios":"Running `skaffold fix` (or any flow triggering implicit upgrade) where the current version in skaffold.yaml cannot be auto-migrated to the target/latest version — typically skipping major schema rewrites.","commonSituations":"Very old configs (skaffold/v1alpha era) being upgraded directly to v4; custom-edited version strings; organizations pinning old schemas that no longer have registered transforms.","solutions":["Upgrade incrementally: run `skaffold fix` step-by-step through intermediate versions (v1 -> v2 -> v3 -> v4) instead of jumping directly.","Manually edit `apiVersion` to the nearest supported version and fix breaking fields by hand.","Regenerate the config with `skaffold init` and re-apply your customizations."],"exampleFix":"// before\napiVersion: skaffold/v1beta10\nkind: Config\n// after: upgrade incrementally\n# skaffold fix  # -> v1...\napiVersion: skaffold/v4beta7\nkind: Config","handlingStrategy":"fallback","validationCode":"cur=$(yq e '.apiVersion' skaffold.yaml)\necho \"$cur\" | grep -qE '^skaffold/v[12]' && echo 'very old schema — plan incremental upgrade via skaffold fix'","typeGuard":null,"tryCatchPattern":"if err := skaffoldFix(cfg); err != nil {\n    var sErr *sErrors.Error\n    if errors.As(err, &sErr) && sErr.ErrCode == proto.StatusCode_CONFIG_UPGRADE_ERR {\n        // fallback: manual incremental migration\n        return migrateIncrementally(cfg, intermediateVersions)\n    }\n    return err\n}","preventionTips":["Upgrade skaffold schemas regularly (each minor release) instead of jumping many versions at once.","Run `skaffold fix` in a dedicated commit and review the diff before updating apiVersion.","Keep configs on released versions (v2/v3/v4), avoiding v1alpha/v1beta lines that lost upgrade paths."],"tags":["config","upgrade","api-version"],"backgroundTag":"config-version-upgrade-unsupported","analyzedSha":"a1189de023efc32d4b8e11f395acc678aa555011","analyzedAt":"2026-09-05T12:09:27.064Z","contentChangedAt":"2026-09-05T12:09:27.064Z","schemaVersion":2},"datasetVersion":"2026-09-12T17:17:11.597Z"}