GoogleContainerTools/skaffold · error

the following versions are incompatible with target version

Error message

the following versions are incompatible with target version %v. upgrade aborted

What it means

IsCompatibleWith in pkg/skaffold/schema/versions.go checks whether every skaffold.yaml config's apiVersion matches the version track (V1 or V2) of the requested target version. If any config's version falls on a different track, the automatic upgrade is refused because skaffold cannot transform configs across major version tracks. It returns (false, err) listing the offending versions.

Source

Thrown at pkg/skaffold/schema/versions.go:381

// IsCompatibleWith checks if the cfgs versions can be upgraded to toVersion.
func IsCompatibleWith(cfgs []util.VersionedConfig, toVersion string) (bool, error) {
	var pattern *regexp.Regexp
	if matched := V1Pattern.MatchString(toVersion); matched {
		pattern = V1Pattern
	} else if matched := V2Pattern.MatchString(toVersion); matched {
		pattern = V2Pattern
	} else {
		return false, fmt.Errorf("target version %v is invalid", toVersion)
	}
	var badVersions []string
	for _, cfg := range cfgs {
		curVersion := cfg.GetVersion()
		if matched := pattern.MatchString(curVersion); !matched {
			badVersions = append(badVersions, curVersion)
		}
	}
	if len(badVersions) > 0 {
		return false, fmt.Errorf(
			"the following versions are incompatible with target version %v. upgrade aborted",
			badVersions)
	}
	return true, nil
}

// UpgradeTo upgrades the given configs to toVersion.
func UpgradeTo(configs []util.VersionedConfig, toVersion string) ([]util.VersionedConfig, error) {
	upgradeNeeded := false
	for _, cfg := range configs {
		// Check that the config's version is not newer than the target version
		currentVersion, err := apiversion.Parse(cfg.GetVersion())
		if err != nil {
			return nil, err
		}
		targetVersion, err := apiversion.Parse(toVersion)
		if err != nil {
			return nil, err

View on GitHub (pinned to a1189de023)

Solutions

1. Bump the apiVersion line in skaffold.yaml to the target major track manually (e.g. change 'skaffold/v1betaN' to the latest v1 line, then re-run).
2. Run `skaffold fix` on each listed config to transform it onto the target version track before calling the API.
3. If the cross-track hop is the problem, upgrade in two steps: first to the latest version of the current track, then to the target track.
4. Ensure all configs in the slice target the same major version track before invoking IsCompatibleWith.

Example fix

// before (skaffold.yaml)
apiVersion: skaffold/v1beta17
kind: Config

// after
apiVersion: skaffold/v2beta29
kind: Config

// check all configs share the target version track before upgrading
for _, cfg := range cfgs {
	v := cfg.GetVersion()
	if (strings.HasPrefix(v, "skaffold/v1") && isV2Target) ||
	   (strings.HasPrefix(v, "skaffold/v2") && isV1Target) {
		return fmt.Errorf("config %v cannot upgrade to %s; run `skaffold fix` first", v, toVersion)
	}
}

func isSameTrack(version, target string) bool {
	track := func(v string) string {
		switch {
		case strings.Contains(v, "v1"): return "v1"
		case strings.Contains(v, "v2"): return "v2"
		default: return "unknown"
		}
	}
	return track(version) == track(target) && track(version) != "unknown"
}

ok, err := schema.IsCompatibleWith(cfgs, toVersion)
if err != nil {
	log.Warnf("auto-upgrade refused: %v — run `skaffold fix` manually", err)
	return err // or fall back to manual migration
}

When it happens

Trigger: Calling IsCompatibleWith(configs, toVersion) where toVersion matches, say, V2Pattern but at least one config's GetVersion() string (e.g. 'skaffold/v1' or a malformed version) does not match the same pattern. Also implicitly hit when a v1 config is present while upgrading toward a v2 target (or vice versa).

Common situations: A developer runs 'skaffold fix --v1' or config parsing/upgrade on a workspace whose skaffold.yaml uses an old major version line (skaffold/v1beta*) that cannot be auto-upgraded to the requested major track, or mixes multiple files/configs with different major versions in one invocation.

Related errors

• config version %q is more recent than target version %q: upg
• transforming skaffold config: %w
• INSPECT_PROFILE_NOT_FOUND_ERR
• cannot resolve active Kubernetes context - multiple contexts
• CONFIG_UNKNOWN_API_VERSION_ERR

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