GoogleContainerTools/skaffold · error

unknown build dependency %q for artifact %q

Error message

unknown build dependency %q for artifact %q

What it means

While walking the dependency graph, dfs looks up each dependency's imageName in the map of defined artifacts. If a dependency references an image that is not defined as an artifact in the config, validation fails because there is nothing to build and no alias mapping for it.

Source

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

// dfs runs a Depth First Search algorithm for cycle detection in a directed graph
func dfs(artifact *latest.Artifact, visited, marked map[string]bool, artifacts map[string]*latest.Artifact) error {
	if marked[artifact.ImageName] {
		return fmt.Errorf("cycle detected in build dependencies involving %q", artifact.ImageName)
	}
	marked[artifact.ImageName] = true
	defer func() {
		marked[artifact.ImageName] = false
	}()
	if visited[artifact.ImageName] {
		return nil
	}
	visited[artifact.ImageName] = true

	for _, dep := range artifact.Dependencies {
		d, found := artifacts[dep.ImageName]
		if !found {
			return fmt.Errorf("unknown build dependency %q for artifact %q", dep.ImageName, artifact.ImageName)
		}
		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{

View on GitHub (pinned to a1189de023)

Solutions

1. Fix the dependency image name to exactly match the image name of a defined artifact
2. Add the missing artifact to build.artifacts if it should be built
3. Remove the dependency if the referenced image is external — external images are not build dependencies

Example fix

// before
artifacts:
  - image: app
    requires: [{ image: ap-typo }]
// after
artifacts:
  - image: base
  - image: app
    requires: [{ image: base }]

// Go: every dependency must name a defined artifact
func unknownDeps(deps map[string][]string, defined map[string]bool) []string {
	var unknown []string
	for src, ds := range deps {
		for _, d := range ds {
			if !defined[d] {
				unknown = append(unknown, src+" -> "+d)
			}
		}
	}
	return unknown
}

if bad := unknownDeps(depGraph, definedArtifacts); len(bad) > 0 {
	return fmt.Errorf("dependencies reference undefined artifacts: %v", bad)
}

When it happens

Trigger: An artifact's buildDependencies[].image names an image that has no corresponding entry under build.artifacts, so artifacts[dep.ImageName] lookup fails.

Common situations: Typo in the dependency image name, referencing an external image (from a registry) as a build dependency, or deleting an artifact but leaving others depending on it.

Related errors

• cycle detected in build dependencies involving %q
• verify command expects non-zero number of test cases
• CONFIG_MISSING_MANIFEST_FILE_ERR
• INIT_CLOUD_RUN_LOCATION_ERROR
• missing apiVersion

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