invalid build dependency for artifact %q: alias %q doesn't m

Error message

invalid build dependency for artifact %q: alias %q doesn't match required pattern %q

What it means

validateValidDependencyAliases enforces that docker and custom artifact dependency aliases match the pattern [a-zA-Z_][a-zA-Z0-9_]*. Aliases are substituted into Dockerfile ARGs / custom script env vars, so they must be valid shell-style identifiers.

Source

Thrown at pkg/skaffold/schema/validation/validation.go:272

		}
		if err := dfs(d, visited, marked, artifacts); err != nil {
			return err
		}
	}
	return nil
}

// validateValidDependencyAliases makes sure that artifact dependency aliases are valid.
// docker and custom builders require aliases match [a-zA-Z_][a-zA-Z0-9_]* pattern
func validateValidDependencyAliases(cfgs *parser.SkaffoldConfigSet, artifacts []*latest.Artifact) (cfgErrs []ErrorWithLocation) {
	for i, a := range artifacts {
		if a.DockerArtifact == nil && a.CustomArtifact == nil {
			continue
		}
		for j, d := range a.Dependencies {
			if !dependencyAliasPattern.MatchString(d.Alias) {
				cfgErrs = append(cfgErrs, ErrorWithLocation{
					Error:    fmt.Errorf("invalid build dependency for artifact %q: alias %q doesn't match required pattern %q", a.ImageName, d.Alias, dependencyAliasPattern.String()),
					Location: cfgs.LocateField(artifacts[i].Dependencies[j], "Alias"),
				})
			}
		}
	}
	return
}

// validateUniqueDependencyAliases makes sure that artifact dependency aliases are unique for each artifact
func validateUniqueDependencyAliases(cfgs *parser.SkaffoldConfigSet, artifacts []*latest.Artifact) (cfgErrs []ErrorWithLocation) {
	type State int
	var (
		unseen   State = 0
		seen     State = 1
		recorded State = 2
	)
	for i, a := range artifacts {
		aliasMap := make(map[string]State)

View on GitHub (pinned to a1189de023)

Solutions

Rename the alias to match [a-zA-Z_][a-zA-Z0-9_]*, e.g. 'base_image' instead of 'base-image'
Update the matching ARG name in the Dockerfile (or env var in the custom script) to the new alias
Start the alias with a letter or underscore, never a digit

Example fix

// before
- image: app
  requires:
    - image: base-image
      alias: base-image
// after
- image: app
  requires:
    - image: base-image
      alias: base_image

Defensive patterns

Strategy: validation

Validate before calling

// Go: alias must match [a-zA-Z_][a-zA-Z0-9_]*
var aliasRe = regexp.MustCompile(`^[a-zA-Z_][a-zA-Z0-9_]*$`)
func validAlias(alias string) bool { return aliasRe.MatchString(alias) }

Try / catch

if !validAlias(alias) {
	return fmt.Errorf("alias %q must match [a-zA-Z_][a-zA-Z0-9_]*", alias)
}

Prevention

Use snake_case aliases; never include hyphens, dots, or leading digits
Keep alias identical to the ARG name in the Dockerfile
Add a YAML lint rule checking aliases against the pattern

When it happens

Trigger: A docker or custom artifact has buildDependencies[].alias containing dashes, dots, a leading digit, or other characters outside the identifier pattern, checked via dependencyAliasPattern.MatchString.

Common situations: Using the image name verbatim ('my-app/api') as an alias, or hyphenated names like 'base-image' that are invalid shell identifiers.

Related errors

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