GoogleContainerTools/skaffold · error

missing apiVersion

Error message

missing apiVersion

What it means

Skaffold's config parser needs to determine the schema version (apiVersion) to select the matching config factory. As a fast pre-parse check, configFactoryFromAPIVersion scans the raw bytes for the string "apiVersion"; if absent, it fails immediately with "missing apiVersion" instead of decoding YAML.

Source

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

	return parseConfig(buf, factories)
}

// ParseConfigAndUpgrade reads a configuration file and upgrades it to a given version.
func ParseConfigAndUpgrade(filename string) ([]util.VersionedConfig, error) {
	configs, err := ParseConfig(filename)
	if err != nil {
		return nil, err
	}

	return UpgradeTo(configs, latest.Version)
}

// configFactoryFromAPIVersion checks that all configs in the input stream have the same API version, and returns a function to create a config with that API version.
func configFactoryFromAPIVersion(buf []byte) ([]func() util.VersionedConfig, error) {
	// This is to quickly check that it's possibly a skaffold.yaml,
	// without parsing the whole file.
	if !bytes.Contains(buf, []byte("apiVersion")) {
		return nil, errors.New("missing apiVersion")
	}

	var factories []func() util.VersionedConfig
	b := bytes.NewReader(buf)
	decoder := yaml.NewDecoder(b)
	for {
		var v APIVersion
		err := decoder.Decode(&v)
		if err == io.EOF {
			break
		}
		if err != nil {
			return nil, fmt.Errorf("parsing api version: %w", err)
		}
		factory, present := AllVersions.Find(v.Version)
		if !present {
			return nil, sErrors.ConfigUnknownAPIVersionErr(v.Version)
		}

View on GitHub (pinned to a1189de023)

Solutions

1. Add `apiVersion: skaffold/<version>` (e.g. skaffold/v4beta7) and a `kind: Config` at the top of your skaffold.yaml.
2. Confirm the file passed via -f/--filename is actually a skaffold config.
3. Run `skaffold init` to generate a correctly structured skaffold.yaml.
4. Fix key spelling/indentation so `apiVersion` appears as a top-level YAML key.

Example fix

// before
kind: Config
deploy:
  kubectl: {}
// after
apiVersion: skaffold/v4beta7
kind: Config
deploy:
  kubectl: {}

const doc = yaml.parse(fs.readFileSync(file, 'utf8'));
if (!doc || typeof doc !== 'object' || !('apiVersion' in doc)) {
  throw new Error(`${file} is not a skaffold config: missing apiVersion`);
}

function isSkaffoldConfig(o) {
  return typeof o === 'object' && o !== null && typeof o.apiVersion === 'string' && o.apiVersion.startsWith('skaffold/') && o.kind === 'Config';
}

try {
  execSync('skaffold config', { stdio: 'pipe' });
} catch (e) {
  if (String(e).includes('missing apiVersion')) console.error('Add apiVersion: skaffold/<ver> to skaffold.yaml');
}

When it happens

Trigger: Passing a YAML file that is not a skaffold config (no apiVersion key) to skaffold commands or the config-parse API; passing JSON that lacks apiVersion; piping empty or truncated files via `-f -`; pointing -f at a README, values.yaml, or Kubernetes manifest without apiVersion.

Common situations: Typos like `api-version:` or `apiVersion :`; accidentally renaming apiVersion key; using an example snippet without the header; feeding a kustomization.yaml (no apiVersion in old versions) to skaffold.

Related errors

• portForward[%d] of config with name '%s' is empty, Please ch
• artifact %s has invalid Jib plugin type '%s'
• skipTrim value not set: %s
• verify command expects non-zero number of test cases
• CONFIG_MISSING_MANIFEST_FILE_ERR

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