GoogleContainerTools/jib · error · IOException

Could not parse layer entry, missing required property 'name

Error message

Could not parse layer entry, missing required property 'name'

What it means

LayerSpec's Jackson deserializer reads the JSON node of a layer entry in a build file and dispatches to ArchiveLayerSpec or FileLayerSpec. Every layer entry must carry a 'name' property; if it does not, the deserializer throws an IOException with this message.

Source

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

@JsonDeserialize(using = LayerSpec.Deserializer.class)
public interface LayerSpec {
  class Deserializer extends StdDeserializer<LayerSpec> {

    public Deserializer() {
      super(LayerSpec.class);
    }

    /**
     * Deserializes to {@link ArchiveLayerSpec} if yaml contains "archive" field, to {@link
     * FileLayerSpec} if yaml contains "files" field or throws {@link IOException} if neither is
     * found or no "name" was specified for the layer entry.
     */
    @Override
    public LayerSpec deserialize(JsonParser jsonParser, DeserializationContext context)
        throws IOException {
      JsonNode node = jsonParser.getCodec().readTree(jsonParser);
      if (!node.has("name")) {
        throw new IOException("Could not parse layer entry, missing required property 'name'");
      }
      if (node.has("archive")) {
        return jsonParser.getCodec().treeToValue(node, ArchiveLayerSpec.class);
      }
      if (node.has("files")) {
        return jsonParser.getCodec().treeToValue(node, FileLayerSpec.class);
      }
      throw new IOException("Could not parse entry into ArchiveLayer or FileLayer");
    }
  }
}

View on GitHub (pinned to fb949e2676)

Solutions

1. Add a 'name' property to every layer entry in the build file.
2. Validate the build file against the documented layer schema before running.
3. If generated, fix the generator to always emit 'name'.

Example fix

// before
{"archive": "app.tar"}
// after
{"name": "app", "archive": "app.tar"}

for (JsonNode layer : buildFile.get("layers")) {
  if (!layer.has("name")) throw new IllegalArgumentException("Layer entry missing 'name': " + layer);
}

try {
  parseBuildFile(json);
} catch (IOException e) {
  if (e.getMessage().contains("missing required property 'name'")) {
    log.error("Build file layer entry needs a 'name' field");
  } else throw e;
}

When it happens

Trigger: Parsing a buildfile (JSON/YAML) whose layers list contains an entry lacking the required 'name' property, e.g. {"archive": "app.tar"} with no name.

Common situations: Hand-editing build files and dropping the name key, generating build files programmatically and omitting required fields, older build-file formats missing name.

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

• Could not parse entry into ArchiveLayer or FileLayer
• Cannot apply includes/excludes on single file copy directive
• octalPermissions must be a 3-digit octal number (000-777)
• The class file (${jarEntry}) is of an invalid format.
• Reached end of class file (${jarEntry}) before being able to

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