CircleCI Workspace Files Overwritten - Fan-In Conflicts

By Daniel Zoghalchali·Latchkey

Several upstream jobs persist to the same workspace paths, and the fan-in job sees clobbered or missing files. When parallel jobs write overlapping paths, the later attach overwrites the earlier - so the combined workspace is not what you expect.

What this error means

A job that requires: several upstream jobs attaches a workspace where some files are missing or replaced by another job’s version. Each upstream job persisted correctly, but their overlapping paths collide on fan-in.

attach_workspace (requires: build-a, build-b)
  - dist/report.json present from build-b only
  - build-a's dist/report.json was overwritten on attach

Common causes

Parallel jobs persist the same paths

Two upstream jobs both persist dist/. On fan-in the workspace layers them, so identically-named files clobber each other unpredictably.

No namespacing per producer

Without writing each job’s output into a distinct subdirectory, there is nothing to keep their files separate when attached together.

Assuming persist merges instead of overlays

Workspaces overlay paths; they do not merge directory contents intelligently. Same-path files from different jobs do not coexist.

How to fix it

Namespace each job’s output under a unique path

jobs:
  build-a:
    steps:
      - run: mkdir -p dist/a && ./build-a.sh -o dist/a
      - persist_to_workspace: { root: ., paths: [dist/a] }
  build-b:
    steps:
      - run: mkdir -p dist/b && ./build-b.sh -o dist/b
      - persist_to_workspace: { root: ., paths: [dist/b] }

Attach once and read per-namespace

1. Give each producer a distinct subdirectory so paths never overlap.
2. In the fan-in job, attach_workspace once and read dist/a, dist/b separately.
3. Avoid persisting broad shared roots from multiple parallel jobs.

How to prevent it

• Namespace each parallel job’s artifacts under a unique path.
• Remember workspaces overlay (not merge) same-named files.
• Keep persisted paths from parallel jobs disjoint.

Frequently asked questions

Related guides

References

• GitHub Actions documentation