CircleCI persist_to_workspace Errors - Fix Workspace Saves

By Kaveh Alemi·Latchkey

persist_to_workspace did not store what you expected to hand to a later job. The paths are relative to root, and a mismatch means the workspace is empty or missing the files the downstream job needs.

What this error means

A later job that runs attach_workspace is missing build artifacts, or the persist step errors that a path does not exist under the root. The handoff between jobs loses data.

persist_to_workspace
  - root: workspace
  - path "dist" not found under root "workspace"
Error: nothing to persist

Common causes

paths are not under root

Each entry in paths is resolved relative to root. Listing dist when the output is at ./dist but root: workspace points elsewhere persists nothing.

Persisting before the files exist

If persist_to_workspace runs before the build produces the artifacts, there is nothing to store.

Root mismatch between persist and attach

The downstream attach_workspace.at should match how you reference the files. A different at location makes the files appear "missing" even though they were persisted.

How to fix it

Set root and paths consistently

jobs:
  build:
    steps:
      - checkout
      - run: npm ci && npm run build   # produces ./dist
      - persist_to_workspace:
          root: .
          paths:
            - dist
            - node_modules

Attach at a matching location downstream

  deploy:
    steps:
      - attach_workspace:
          at: .
      - run: ls dist && ./deploy.sh

How to prevent it

• Persist after the build, with paths relative to root.
• Use a consistent root / at convention across jobs.
• List ls of the attached dir in the downstream job while debugging.

Frequently asked questions

Related guides

References

• GitHub Actions documentation