🚨 GitLab CI Error Guide: 'Downloading artifacts ... invalid argument' Extraction

Exact Error Message

A downstream job fails while pulling artifacts from an upstream job:

Downloading artifacts for build (84219)...
Downloading artifacts from coordinator... ok    id=84219 responseStatus=200 OK
ERROR: Downloading artifacts from coordinator... invalid argument
  id=84219 responseStatus=200 OK
FATAL: invalid argument
ERROR: Job failed: exit status 1

The HTTP request itself succeeds (200 OK), but the runner then fails with invalid argument while extracting the archive onto the job’s filesystem. The same wording can appear during upload when a path inside artifacts:paths is malformed.

What the Error Means

invalid argument here is the operating system’s EINVAL surfacing from a syscall the runner makes while writing the artifact archive to disk. The download transferred fine; the failure is in the extraction step. Common triggers are filenames the target filesystem rejects (illegal characters, paths that are too long, reserved names on Windows), a path that escapes the build directory, or a corrupt/zero-length archive.

It is a filesystem/extraction problem, not an auth or network one — which is why you see 200 OK immediately before the failure.

Common Causes

1. Illegal filenames for the target filesystem — colons, backslashes, or control characters created on Linux but extracted on a Windows runner.
2. Path too long for the filesystem (very deep node_modules trees on systems with path-length limits).
3. Absolute or ..-escaping paths baked into artifacts:paths, rejected on extraction.
4. Corrupt or truncated archive from an interrupted upload or storage error.
5. A symlink or special file the runner can’t recreate on the destination filesystem.

How to Reproduce the Error

Create an artifact containing a filename that is legal on Linux but invalid on the consuming runner’s filesystem, or an empty/corrupt archive:

build:
  image: alpine:3.20
  script:
    - mkdir -p out
    - touch "out/report:final.txt"   # colon is illegal on some filesystems
  artifacts:
    paths: ["out/"]

deploy:
  needs: ["build"]
  script:
    - ls out/

When deploy runs on a runner whose filesystem rejects the colon:

ERROR: Downloading artifacts from coordinator... invalid argument
FATAL: invalid argument

Diagnostic Commands

Read-only checks to find the offending entry. Run inside the producing job before upload:

# List artifact files and flag unusual characters
find out -print | LC_ALL=C grep -nP '[\x00-\x1f:\\*?"<>|]'

# Spot extremely long paths
find out -print | awk '{ if (length > 240) print length, $0 }'

# Detect absolute or parent-escaping paths in your config intent
find out -path '/*' -o -name '..'

# Confirm the archive isn't zero-length (on the runner host cache, if accessible)
ls -l artifacts.zip 2>/dev/null

12:out/report:final.txt

A match from the first command (an illegal character) or a path over the filesystem limit pinpoints the entry the runner cannot extract.

Step-by-Step Resolution

1. Remove illegal characters from artifact filenames

Rename outputs to use portable characters before they become artifacts:

build:
  script:
    - mkdir -p out
    - mv "out/report:final.txt" "out/report-final.txt" 2>/dev/null || true
  artifacts:
    paths: ["out/report-final.txt"]

Stick to [A-Za-z0-9._-] in generated filenames so any consuming filesystem accepts them.

2. Keep paths relative and inside the build dir

artifacts:paths must be relative to CI_PROJECT_DIR. Absolute paths or .. escapes fail on extraction:

artifacts:
  paths:
    - build/output      # good: relative
    # - /tmp/output     # bad: absolute, will not extract

3. Shorten deep paths and exclude bulky trees

Excluding node_modules/ both shrinks the archive and removes the deepest paths that hit length limits:

artifacts:
  exclude:
    - "**/node_modules/**"

4. Rule out a corrupt archive

If the names look fine, the archive may be truncated from an interrupted upload. Re-run the producing job to regenerate it, then re-run the consumer. A fresh artifact with the same invalid argument points back to a path/filename issue rather than corruption.

5. Match producer and consumer filesystems

If the producer runs on Linux and the consumer on Windows, prefer artifacts without colons, trailing dots, or reserved names (CON, NUL). Where possible, run dependent jobs on the same OS family.

Prevention and Best Practices

• Generate artifact filenames from a safe character set; never embed timestamps with : or arbitrary user input in filenames.
• Keep artifacts:paths relative and scoped; exclude node_modules/, .git/, and source maps to avoid deep/long paths.
• Pin producer and consumer jobs to the same OS family when filenames might be borderline portable.
• Re-run the producing job to rule out a truncated archive before chasing filename issues.
• Dropping the failing extraction log into the free incident assistant helps separate a corrupt archive from an illegal-path problem. More patterns live in the GitLab CI/CD guides.

Related Errors

• Downloading artifacts … 404 Not Found — the artifact expired or was never produced; a download-stage failure but with a 404, not invalid argument.
• Uploading artifacts … 413 Request Entity Too Large — the upload-side size rejection; same subsystem, different stage.
• archive/tar: invalid tar header — a genuinely corrupt archive; regenerate it from the producing job.

Frequently Asked Questions

The log says 200 OK right before the error — so the download worked?

Yes. The transfer from the coordinator succeeded; the invalid argument comes from the extraction step writing files to disk. Focus on filenames, path length, and archive integrity rather than network or auth.

Why does it only fail on some runners?

Different filesystems (and operating systems) reject different characters and path lengths. A colon in a filename is fine on ext4 but illegal on NTFS, so the same artifact extracts on one runner and fails on another. Use portable filenames everywhere.

Could the archive simply be corrupt?

Possibly. An interrupted upload or storage glitch can truncate the archive. Re-run the producing job to regenerate it. If the error persists with a fresh, clean artifact, the cause is an illegal path or filename, not corruption.

Are absolute paths in artifacts:paths allowed?

No. Paths must be relative to the project directory. Absolute paths or .. that escape the build directory are rejected on extraction with invalid argument. Keep every path relative and inside CI_PROJECT_DIR.