What causes "${src} is not a parent of ${path}" in GoogleContainerTools/jib?

Replace out-of-tree symlinks with real copies of the target content before building.

GoogleContainerTools/jib · error · IllegalStateException

${src} is not a parent of ${path}

Error message

${src} is not a parent of ${path}

What it means

While adding regular-file entries from a directory walk, Layers.toLayers asserts every file is under the resolved src tree; otherwise it cannot compute parent directories consistently. This usually arises from filesystem link scenarios Jib does not model. When a walked path does not start with src, it throws IllegalStateException '<src> is not a parent of <path>'.

Source

Thrown at jib-cli/src/main/java/com/google/cloud/tools/jib/cli/buildfile/Layers.java:151

                          filePropertiesStack.getOwnership());

              Set<Path> addedDirectories = new HashSet<>();
              for (Path path : filtered) {
                if (!Files.isDirectory(path) && !Files.isRegularFile(path)) {
                  throw new UnsupportedOperationException(
                      "Cannot create FileLayers from non-file, non-directory: " + src.toString());
                }

                if (Files.isDirectory(path)) {
                  addedDirectories.add(path);
                  layerBuiler.addEntry(
                      newEntry.apply(path, filePropertiesStack.getDirectoryPermissions()));
                } else if (Files.isRegularFile(path)) {
                  if (!path.startsWith(src)) {
                    // if we end up in a situation where the file added is somehow outside of the
                    // tree then we do not know how to properly handle it at the moment. It could
                    // be from a link scenario that we do not understand.
                    throw new IllegalStateException(
                        src.toString() + " is not a parent of " + path.toString());
                  }
                  Path parent = Verify.verifyNotNull(path.getParent());
                  while (true) {
                    if (addedDirectories.contains(parent)) {
                      break;
                    }
                    layerBuiler.addEntry(
                        newEntry.apply(parent, filePropertiesStack.getDirectoryPermissions()));
                    addedDirectories.add(parent);
                    if (parent.equals(src)) {
                      break;
                    }
                    parent = Verify.verifyNotNull(parent.getParent());
                  }
                  layerBuiler.addEntry(
                      newEntry.apply(path, filePropertiesStack.getFilePermissions()));
                }

View on GitHub (pinned to fb949e2676)

Solutions

Replace out-of-tree symlinks with real copies of the target content before building.
Remove symlinks in the copied directory that escape the src tree.
Restructure the source layout so all referenced content lives under the src directory.
Split the copy into multiple specs copying the real directories directly.

Example fix

// before
build/ -> /somewhere/else  (symlink escaping src)
// after
cp -rL /somewhere/else build/  // materialize real files inside src

Defensive patterns

Strategy: validation

Validate before calling

try (var walk = Files.walk(srcDir)) {
  var escaping = walk.filter(Files::isRegularFile)
      .filter(p -> !p.toRealPath().startsWith(srcDir.toRealPath()))
      .toList();
  if (!escaping.isEmpty()) throw new IllegalStateException("Symlinks escape src tree: " + escaping);
}

Try / catch

try {
  jibBuild();
} catch (IllegalStateException e) {
  if (e.getMessage().contains("is not a parent of")) {
    log.error("Copy tree contains symlinks pointing outside the source directory");
  } else throw e;
}

Prevention

Avoid symlinks that escape the copied directory (node_modules global stores, etc.)
Use cp -rL to materialize real files before building
Keep copied trees self-contained under the src path

When it happens

Trigger: Directory copy where the walked tree contains symlinks pointing outside the src directory (or hard-to-resolve link layouts) such that a discovered regular file path is not a descendant of the resolved src.

Common situations: Symlinked directories pointing outside the build root (e.g. node_modules symlinks to a global store), symlink chains escaping the copied tree.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of GoogleContainerTools/jib@fb949e2676 (2026-09-06). Data as JSON: /api/errors/571f8279ec32a9dc. Report an issue: GitHub.