GoogleContainerTools/skaffold · error

CONFIG_UPGRADE_ERR

CONFIG_UPGRADE_ERR

Error message

skaffold cannot auto-upgrade the config from version %s to version %s

What it means

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.

Source

Thrown at pkg/skaffold/schema/errors/errors.go:208

func ConfigUnknownAPIVersionErr(version string) error {
	msg := fmt.Sprintf("unknown skaffold config API version %q", version)
	return sErrors.NewError(errors.New(msg),
		&proto.ActionableErr{
			Message: msg,
			ErrCode: proto.StatusCode_CONFIG_UNKNOWN_API_VERSION_ERR,
			Suggestions: []*proto.Suggestion{
				{
					SuggestionCode: proto.SuggestionCode_CONFIG_FIX_API_VERSION,
					Action:         "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",
				},
			},
		})
}

// SkaffoldConfigUpgradeErr specifies that skaffold config needs to be upgraded to the latest version.
func SkaffoldConfigUpgradeErr(currentVersion, targetVersion string) error {
	msg := fmt.Sprintf("skaffold cannot auto-upgrade the config from version %s to version %s", currentVersion, targetVersion)
	return sErrors.NewError(errors.New(msg),
		&proto.ActionableErr{
			Message: msg,
			ErrCode: proto.StatusCode_CONFIG_UPGRADE_ERR,
			Suggestions: []*proto.Suggestion{
				{
					SuggestionCode: proto.SuggestionCode_CONFIG_FIX_SKAFFOLD_CONFIG_VERSION,
					Action:         fmt.Sprintf("Upgrade skaffold config version to %s manually", targetVersion),
				},
			},
		})
}

View on GitHub (pinned to a1189de023)

Solutions

1. Upgrade incrementally: run `skaffold fix` step-by-step through intermediate versions (v1 -> v2 -> v3 -> v4) instead of jumping directly.
2. Manually edit `apiVersion` to the nearest supported version and fix breaking fields by hand.
3. Regenerate the config with `skaffold init` and re-apply your customizations.

Example fix

// before
apiVersion: skaffold/v1beta10
kind: Config
// after: upgrade incrementally
# skaffold fix  # -> v1...
apiVersion: skaffold/v4beta7
kind: Config

cur=$(yq e '.apiVersion' skaffold.yaml)
echo "$cur" | grep -qE '^skaffold/v[12]' && echo 'very old schema — plan incremental upgrade via skaffold fix'

if err := skaffoldFix(cfg); err != nil {
    var sErr *sErrors.Error
    if errors.As(err, &sErr) && sErr.ErrCode == proto.StatusCode_CONFIG_UPGRADE_ERR {
        // fallback: manual incremental migration
        return migrateIncrementally(cfg, intermediateVersions)
    }
    return err
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• CONFIG_UNKNOWN_API_VERSION_ERR
• bucket name is empty
• INSPECT_PROFILE_NOT_FOUND_ERR
• cannot resolve active Kubernetes context - multiple contexts
• CONFIG_BAD_FILTER_ERR

AI-assisted analysis of GoogleContainerTools/skaffold@a1189de023 (2026-09-05). Data as JSON: /api/errors/378947bd620b5bd9. Report an issue: GitHub.