🚨 GitLab CI Error Guide: 'Uploading artifacts ... 413 Request Entity Too Large'

Exact Error Message

An otherwise successful job fails at the very end while uploading its artifacts:

Uploading artifacts...
dist/: found 2417 matching artifact files and directories
Uploading artifacts as "archive" to coordinator... 413 Request Entity Too Large
  id=84213 responseStatus=413 Request Entity Too Large status=413
FATAL: Request Entity Too Large
ERROR: Job failed: exit status 1

The build itself passed. The failure is purely the runner trying to push the artifact archive to GitLab and being rejected with HTTP 413.

What the Error Means

413 Request Entity Too Large is an HTTP status returned by GitLab (or a reverse proxy in front of it) saying the artifact upload exceeds a configured size limit. There are two independent ceilings that can produce it:

1. GitLab’s max_artifacts_size — an application-level cap (default 100 MB on many self-managed installs; per-project/group overrides exist on GitLab.com).
2. The reverse proxy body limit — NGINX’s client_max_body_size (bundled GitLab defaults to 250m via nginx['client_max_body_size']), or a load balancer/ingress limit in front of GitLab.

Whichever limit is smaller wins. The runner has already compressed the archive, so the upload is a single large request that one of these limits rejects.

Common Causes

1. Artifact archive larger than max_artifacts_size for the instance, group, or project.
2. Reverse proxy client_max_body_size lower than the artifact size (common behind a custom NGINX/HAProxy/Ingress).
3. Over-broad artifacts:paths sweeping node_modules/, .git/, or the whole workspace.
4. Uncompressed large binaries (build outputs, container tarballs, datasets) being archived.
5. An external object-storage proxy with its own request-size limit on the upload path.

How to Reproduce the Error

Produce a large artifact on an instance with a modest limit:

build:
  image: alpine:3.20
  script:
    - mkdir -p dist
    - dd if=/dev/urandom of=dist/blob.bin bs=1M count=400
  artifacts:
    paths:
      - dist/

Uploading artifacts as "archive" to coordinator... 413 Request Entity Too Large
FATAL: Request Entity Too Large
ERROR: Job failed: exit status 1

Diagnostic Commands

Read-only checks to find which limit you are hitting and how big the artifact really is:

# How big is the archive the runner would upload? (run inside the job)
du -sh dist/
tar czf - dist/ | wc -c

# List the biggest contributors so you can trim paths
du -ah dist/ | sort -rh | head -20

# On a self-managed instance: read the application artifact cap
grep -n max_artifacts_size /etc/gitlab/gitlab.rb

# Read the bundled NGINX body limit
grep -n client_max_body_size /etc/gitlab/gitlab.rb /var/opt/gitlab/nginx/conf/*.conf

412M    dist/
client_max_body_size 250m;

If du -sh exceeds either printed limit, you have found the cause. A 250m NGINX limit against a 412M archive explains the 413 directly.

Step-by-Step Resolution

1. Shrink the artifact first

The cheapest fix is to upload less. Scope artifacts:paths to only what downstream jobs need and exclude bulky inputs:

artifacts:
  paths:
    - dist/app
  exclude:
    - dist/**/*.map
    - "**/node_modules/**"

For large binaries that only need to exist later, prefer pushing them to object storage or a package registry instead of CI artifacts.

2. Raise GitLab’s application limit (self-managed)

In the Admin Area, Settings > CI/CD > Continuous Integration and Deployment, increase Maximum artifacts size (MB). Project and group settings can override it downward, so check those too. There is no edit needed on GitLab.com beyond plan limits.

3. Raise the reverse proxy body limit

For bundled NGINX, edit /etc/gitlab/gitlab.rb:

nginx['client_max_body_size'] = '1024m'

Then apply with sudo gitlab-ctl reconfigure. If you run your own NGINX, ingress, or load balancer in front of GitLab, raise client_max_body_size (or the equivalent) there as well — that external limit is invisible to GitLab’s own settings.

4. Use expiry and when to avoid hoarding

Keep artifacts only as long as needed so storage limits do not compound:

artifacts:
  expire_in: 1 week
  when: on_success

5. Re-run and confirm

After trimming paths and aligning both limits above the archive size, the upload completes with a normal Uploading artifacts ... 201 Created.

Prevention and Best Practices

• Keep both ceilings in sync: there is no point raising max_artifacts_size if NGINX client_max_body_size is still lower.
• Pass build outputs between jobs only when needed; for cross-pipeline reuse, push to a package registry or object store rather than artifacts.
• Always set exclude for source maps, node_modules/, and .git/ so archives stay lean.
• Set expire_in on every job to keep storage and upload sizes predictable.
• Pasting the failing upload log into the free incident assistant quickly tells you whether you hit the app limit or the proxy limit. More patterns live in the GitLab CI/CD guides.

Related Errors

• ERROR: Uploading artifacts ... too large archive — the runner-side size guard rather than an HTTP 413; both mean the artifact is too big.
• 502 Bad Gateway on artifact upload — usually a proxy timeout on a slow large upload, related but distinct from a size rejection.
• Downloading artifacts ... 404 — the download counterpart; artifacts expired or were never uploaded.

Frequently Asked Questions

The job’s script passed — why does it still fail?

Artifact upload happens after your script as a separate step. A 413 during upload fails the whole job even though your build succeeded. Look at the very last lines of the log for the Uploading artifacts section.

I raised max_artifacts_size but still get 413. Why?

A reverse proxy in front of GitLab (bundled NGINX, ingress, or a load balancer) has its own client_max_body_size. Raise that too — it is enforced before the request ever reaches the GitLab application limit.

How do I find which files are bloating the archive?

Run du -ah dist/ | sort -rh | head -20 inside the job to list the biggest contributors. Most 413s come from accidentally including node_modules/, .git/, or build caches; add them to artifacts:exclude.

Is there a smarter alternative to huge artifacts?

Yes. For binaries reused across pipelines, push to the GitLab Package Registry or object storage and pull them where needed. Artifacts are best for small-to-medium outputs passed between jobs in the same pipeline.