slimtoolkit/slim · error

too many layers

Error message

too many layers

What it means

Engine.Build rejects build options when more than 255 layer entries are supplied. OCI/Docker images have a practical layer-count limit and the builder enforces a hard cap of 255 to keep the produced image valid and buildable. If options.Layers contains 256 or more entries the build fails immediately before any image is created.

Source

Thrown at pkg/imagebuilder/internalbuilder/engine.go:62

		PushToDaemon:   pushToDaemon,
		PushToRegistry: pushToRegistry,
	}

	return engine, nil
}

func (ref *Engine) Build(options imagebuilder.SimpleBuildOptions) (*imagebuilder.ImageResult, error) {
	if len(options.ImageConfig.Config.Entrypoint) == 0 &&
		len(options.ImageConfig.Config.Cmd) == 0 {
		return nil, fmt.Errorf("missing startup info")
	}

	if len(options.Layers) == 0 {
		return nil, fmt.Errorf("no layers")
	}

	if len(options.Layers) > 255 {
		return nil, fmt.Errorf("too many layers")
	}

	switch options.ImageConfig.Architecture {
	case "":
		options.ImageConfig.Architecture = "amd64"
	case "arm64", "amd64":
	default:
		return nil, fmt.Errorf("bad architecture value")
	}

	var img v1.Image
	if options.From == "" {
		//same as FROM scratch
		img = empty.Image
	} else {
		return nil, fmt.Errorf("custom base images are not supported yet")
	}

View on GitHub (pinned to 81940d17fa)

Solutions

1. Consolidate files into fewer tar archives so the Layers slice has 255 or fewer entries
2. Combine multiple directories into a single DirSource layer per logical root
3. Filter out unnecessary artifacts before building to reduce layer count
4. If the limit is genuinely blocking, raise the 255 cap in pkg/imagebuilder/internalbuilder/engine.go (validate against the target runtime first)

Example fix

// before
for _, f := range files {
    layers = append(layers, imagebuilder.LayerDataInfo{Type: imagebuilder.TarSource, Source: f})
}
// after
// batch files into archives so len(layers) <= 255
batch := tarBatch(files, 255)
for _, tarPath := range batch {
    layers = append(layers, imagebuilder.LayerDataInfo{Type: imagebuilder.TarSource, Source: tarPath})
}

if len(opts.Layers) > 255 {
    return fmt.Errorf("build needs <=255 layers, got %d", len(opts.Layers))
}

if _, err := engine.Build(opts); err != nil {
    if strings.Contains(err.Error(), "too many layers") {
        // consolidate layer sources and retry once
    }
    return err
}

When it happens

Trigger: Calling imagebuilder Engine.Build (via slim build) with SimpleBuildOptions.Layers containing >255 LayerDataInfo entries, e.g. when a large artifact set is expanded into one layer per file.

Common situations: Programmatic image generation that maps one artifact/file per layer instead of batching; scripts that accumulate layers in a loop without consolidation; large application bundles producing hundreds of tar/directory layers.

Related errors

• empty image layer data source
• image layer data source path is not a tar file - %s
• unknown image data source - %v
• no layers
• bad architecture value

AI-assisted analysis of slimtoolkit/slim@81940d17fa (2026-08-31). Data as JSON: /api/errors/daf3adb188be0ad5. Report an issue: GitHub.