GoogleContainerTools/skaffold · error

CONFIG_UNKNOWN_API_VERSION_ERR

CONFIG_UNKNOWN_API_VERSION_ERR

Error message

unknown skaffold config API version %q

What it means

ConfigUnknownAPIVersionErr is thrown when the `apiVersion` in skaffold.yaml does not match any known skaffold schema version. Code CONFIG_UNKNOWN_API_VERSION_ERR, suggesting fixing the API version string.

Source

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

func ConfigProfileConflictErr(config, file string) error {
	msg := fmt.Sprintf("config %q defined in file %q imported multiple times with different set of profiles", config, file)
	return sErrors.NewError(errors.New(msg),
		&proto.ActionableErr{
			Message: msg,
			ErrCode: proto.StatusCode_CONFIG_MULTI_IMPORT_PROFILE_CONFLICT_ERR,
			Suggestions: []*proto.Suggestion{
				{
					SuggestionCode: proto.SuggestionCode_CONFIG_CHECK_DEPENDENCY_PROFILES_SELECTION,
					Action:         "Check that all occurrences of the specified config dependency use the same set of profiles; refer to the documentation on how to author config dependencies: https://skaffold.dev/docs/design/config/#configuration-dependencies",
				},
			},
		})
}

// ConfigUnknownAPIVersionErr specifies that the config API version doesn't match any known versions.
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,

View on GitHub (pinned to a1189de023)

Solutions

1. Set `apiVersion` to a valid version, e.g. the latest `skaffold/v4beta7` (or a released v3/v2 version).
2. Run `skaffold fix` to migrate the config to the latest schema automatically.
3. Upgrade or downgrade the skaffold binary to one that supports the version in the file.

Example fix

// before
apiVersion: skaffold/v4beta12
kind: Config
// after (with an older skaffold binary)
apiVersion: skaffold/v4beta7
kind: Config

ver=$(yq e '.apiVersion' skaffold.yaml)
supported=(skaffold/v1 skaffold/v1alpha* skaffold/v2* skaffold/v3* skaffold/v4*)
case "$ver" in skaffold/v[1-4]*) echo ok;; *) echo "unknown apiVersion: $ver"; exit 1;; esac

if err != nil {
    var sErr *sErrors.Error
    if errors.As(err, &sErr) && sErr.ErrCode == proto.StatusCode_CONFIG_UNKNOWN_API_VERSION_ERR {
        return fmt.Errorf("%w — run `skaffold fix` or pin a supported apiVersion", err)
    }
    return err
}

When it happens

Trigger: Parsing skaffold.yaml whose `apiVersion` field (e.g. `skaffold/v99`, a typo like `skaffold/v3`, or missing the `skaffold/` prefix) is not registered in the schema store.

Common situations: Hand-editing or AI-generating configs with an invented version; upgrading skaffold on CI where an old client doesn't know a newer schema version; copy-pasting configs between projects with different version lines.

Related errors

• CONFIG_UPGRADE_ERR
• the following versions are incompatible with target version
• transforming skaffold config: %w
• Unknown artifact
• bucket name is empty

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