GitLab CI "Preparation failed: file too large" - Artifacts Over Max

By Daniel Zoghalchali·Latchkey

GitLab enforces a maximum artifact size per job. When the uploaded artifacts exceed the instance or project limit, the runner reports the upload failed because the file is too large.

What this error means

The job fails at artifact upload with a too-large or 413-style message, naming the artifact that exceeded the maximum size.

gitlab-ci

ERROR: Uploading artifacts as "archive" to coordinator... too large archive
id=12345 responseStatus=413 Request Entity Too Large
FATAL: too large

Common causes

Artifact set exceeds the max size

The total uploaded artifacts exceed the instance maximum_artifacts_size limit.

Including build caches or node_modules

Accidentally capturing large directories like node_modules or build caches bloats the artifact.

How to fix it

Narrow the artifact paths

Upload only what downstream jobs need and exclude heavy directories.

.gitlab-ci.yml

build:
  artifacts:
    paths:
      - dist/
    exclude:
      - dist/**/*.map

Raise the limit or split outputs

For self-managed, raise maximum_artifacts_size in admin settings if appropriate.
Split large outputs across multiple jobs or use external object storage.
Compress before uploading where it helps.

How to prevent it

Scope artifacts:paths tightly to required outputs.
Exclude caches, maps, and node_modules from artifacts.
Monitor artifact sizes against the instance limit.

Frequently asked questions

What causes ""file too large" artifacts"?