goharbor/harbor · error · lib/errors.Error

REQUEST_ENTITY_TOO_LARGE

REQUEST_ENTITY_TOO_LARGE

Error message

The file is too large to be processed

What it means

The base parser for CNAI (Harbor's AI artifact type) refuses to materialize addition layers larger than defaultFileSizeLimit (4MB), returning an error mapped to HTTP 413 Request Entity Too Large. There are two checks: a cheap pre-check on the manifest-declared layer.Size, and a second check on the actual bytes materialized when pulling/untarring the layer, so decompression or sparse-tar bombs that expand past 4MB are also rejected.

Source

Thrown at src/controller/artifact/processor/cnai/parser/base.go:32

package parser // nolint:revive

import (
	"context"
	"fmt"
	"io"
	"path/filepath"

	ocispec "github.com/opencontainers/image-spec/specs-go/v1"

	"github.com/goharbor/harbor/src/lib/errors"
	"github.com/goharbor/harbor/src/pkg/artifact"
	"github.com/goharbor/harbor/src/pkg/registry"
)

var (
	// errFileTooLarge is returned when the file is too large to be processed.
	errFileTooLarge = errors.New("The file is too large to be processed")
)

const (
	// contentTypeTextPlain is the content type of text/plain.
	contentTypeTextPlain = "text/plain; charset=utf-8"
	// contentTypeTextMarkdown is the content type of text/markdown.
	contentTypeMarkdown = "text/markdown; charset=utf-8"
	// contentTypeJSON is the content type of application/json.
	contentTypeJSON = "application/json; charset=utf-8"

	// defaultFileSizeLimit is the default file size limit.
	defaultFileSizeLimit = 1024 * 1024 * 4 // 4MB

	// formatTar is the format of tar file.
	formatTar = ".tar"
	// formatRaw is the format of raw file.
	formatRaw = ".raw"
)

View on GitHub (pinned to 7b2fd08cc5)

Solutions

1. Keep each readme/license/files layer under 4MB — trim or split the content and push a new version
2. Prefer the .raw layer format for large text and reference external storage for big assets
3. For .tar layers, exclude huge or sparse members when packaging the artifact
4. The 4MB limit is a code constant (defaultFileSizeLimit), not a runtime setting — if it must change, rebuild harbor-core

Example fix

# before: README layer is 12MB -> 413 on additions request
# after: trim the file and push the smaller layer
truncate -s 3M model-card.md   # keep layer and its tar-expanded size <= 4MB

// producer-side, before pushing a CNAI addition layer
const maxAdditionLayerSize = 4 * 1024 * 1024 // mirrors defaultFileSizeLimit
if layer.Size > maxAdditionLayerSize {
    return fmt.Errorf("layer %s is %d bytes; additions layers must stay under 4MB (declared AND expanded)", layer.Digest, layer.Size)
}

if err := parser.Parse(ctx, art, layer); err != nil {
    var tooLarge *errors.Error
    if errors.As(err, &tooLarge) && tooLarge.Code == errors.RequestEntityTooLargeCode {
        // repack the layer smaller; retrying the same blob will fail identically
    }
}

When it happens

Trigger: Requesting the readme/license/files addition on a CNAI artifact whose relevant layer (media type with .tar or .raw extension) is declared larger than 4MB, or whose content expands beyond 4MB when decoded (readAllLimited / untar).

Common situations: AI model artifacts packaging multi-megabyte model cards or README files, gzipped layers that decompress well past their blob size, sparse tar members inside the layer.

Related errors

• purge upload age should set with with nh, n is the number of
• BAD_REQUEST
• NOT_FOUND
• VIOLATE_FOREIGN_KEY_CONSTRAINT
• BAD_REQUEST

AI-assisted analysis of goharbor/harbor@7b2fd08cc5 (2026-08-16). Data as JSON: /api/errors/d179583ba4339daf. Report an issue: GitHub.