GoogleContainerTools/jib · error · IllegalArgumentException

Incomplete <permission> configuration; requires <file> and <

Error message

Incomplete <permission> configuration; requires <file> and <mode> fields to be set

What it means

A <permission> entry in the extra directories configuration is missing either its <file> or <mode> field. MojoCommon.convertPermissionsList requires both to be present and throws IllegalArgumentException otherwise, since a permission without a target file or an octal mode is meaningless.

Source

Thrown at jib-maven-plugin/src/main/java/com/google/cloud/tools/jib/maven/MojoCommon.java:144

            "/"));
  }

  /**
   * Converts a list of {@link PermissionConfiguration} to an equivalent {@code
   * String->FilePermission} map.
   *
   * @param permissionList the list to convert
   * @return the resulting map
   */
  static Map<String, FilePermissions> convertPermissionsList(
      List<PermissionConfiguration> permissionList) {
    // Order is important, so use a LinkedHashMap
    Map<String, FilePermissions> permissionsMap = new LinkedHashMap<>();
    for (PermissionConfiguration permission : permissionList) {
      Optional<String> file = permission.getFile();
      Optional<String> mode = permission.getMode();
      if (!file.isPresent() || !mode.isPresent()) {
        throw new IllegalArgumentException(
            "Incomplete <permission> configuration; requires <file> and <mode> fields to be set");
      }
      permissionsMap.put(file.get(), FilePermissions.fromOctalString(mode.get()));
    }
    return permissionsMap;
  }

  /**
   * Check that the actual version satisfies required Jib version range when specified. No check is
   * performed if the provided Jib version is {@code null}, which should only occur during debug.
   *
   * @param descriptor the plugin version
   * @throws MojoExecutionException if the version is not acceptable
   */
  public static void checkJibVersion(PluginDescriptor descriptor) throws MojoExecutionException {
    String acceptableVersionSpec = System.getProperty(MojoCommon.REQUIRED_VERSION_PROPERTY_NAME);
    if (acceptableVersionSpec == null) {
      return;

View on GitHub (pinned to fb949e2676)

Solutions

1. Provide both fields in every <permission>: <permission><file>/path/in/container</file><mode>755</mode></permission>.
2. Ensure <mode> is a valid octal string (e.g. 644, 755) — set it if it was accidentally cleared.
3. Check that Maven properties used inside <file>/<mode> resolve to non-empty values in the active build profile.
4. Remove empty leftover <permission> elements from previous edits.

Example fix

<!-- before -->
<permissions>
  <permission><file>/app/start.sh</file></permission>
</permissions>

<!-- after -->
<permissions>
  <permission>
    <file>/app/start.sh</file>
    <mode>755</mode>
  </permission>
</permissions>

// Pre-validate permissions entries:
// each <permission> needs both <file> and <mode>
// e.g. xmllint --xpath '//permission[file and mode]' pom.xml || echo 'permission missing file or mode'

try {
  // jib build
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("requires <file> and <mode> fields")) {
    // fill in the missing <file> or <mode> on the offending <permission>
  }
  throw e;
}

When it happens

Trigger: Declaring <extraDirectories><permissions><permission><file>/app/run.sh</file></permission></permissions></extraDirectories> without <mode>, or with <mode> but no <file>, or an empty <permission> element.

Common situations: Hand-editing pom.xml and deleting one of the two fields; property-driven generation leaving a field blank when a Maven property is unset; misunderstanding that both fields are mandatory per permission entry.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• extension ${extension.getClass().getSimpleName()} does not e
• extension-specific <configuration> for ${extension.getClass(
• Incomplete <extraDirectories><paths> configuration; source d
• CacheDirectoryCreationException wrapping IOException from ca
• <container><appRoot> is not an absolute Unix-style path: ${e

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