In a CircleCI workflow, a downstream job cannot find the build output an earlier job produced. How do CircleCI's workspaces, caches, and artifacts differ, and which one should carry that output?

## Start from the invariant Every job in a CircleCI workflow runs on its own freshly provisioned executor. The `checkout` step gives it source code; nothing else from a previous job is present. Any file that needs to cross a job boundary must be handed across deliberately. CircleCI gives you three mechanisms for moving files, and confusing them is one of the most common real-world configuration bugs — each failure mode is distinct and each is quietly misleading. ## Workspaces: within one workflow run A workspace is the correct answer for build output. The producing job persists paths; consuming jobs attach them. ```yaml jobs: build: docker: - image: cimg/node:20.11 steps: - checkout - run: npm ci && npm run build - persist_to_workspace: root: . paths: - dist deploy: docker: - image: cimg/node:20.11 steps: - attach_workspace: at: . - run: ./scripts/deploy.sh dist workflows: ship: jobs: - build - deploy: requires: - build ``` The properties that matter: a workspace is **scoped to one workflow run**, it is **additive** (several upstream jobs can each contribute paths), and content flows only from jobs a consumer actually depends on through `requires`. `root` is the directory the listed `paths` are relative to; `at` is where the consumer materializes them. Forgetting `requires` is the classic bug — the deploy job may start before build finishes, attach an empty or partial workspace, and fail with a missing-file error that looks like a build problem. Workspaces also make **build-once, promote-many** possible inside a pipeline: compile the artifact in one job and let test, scan and deploy jobs all attach the identical bytes rather than each rebuilding. ## Caches: across runs, for things you could refetch A cache is saved and restored by explicit key: ```yaml - restore_cache: keys: - v1-deps-{{ checksum "package-lock.json" }} - v1-deps- - run: npm ci - save_cache: key: v1-deps-{{ checksum "package-lock.json" }} paths: - ~/.npm ``` `restore_cache` takes an ordered list and uses the first key that matches; a key that is a prefix of stored keys performs a partial match, which is why the second, looser entry acts as a fallback when the lockfile changed. Template helpers such as `{{ checksum "file" }}`, `{{ .Branch }}` and `{{ arch }}` build keys that change when their inputs change. The leading `v1-` is a manual escape hatch: bump it to invalidate everything at once. The property that produces incidents: **a cache key is write-once**. If `save_cache` targets a key that already exists, the save is skipped rather than overwriting. That is exactly right for content-addressed dependency caches — the content for a given lockfile checksum never needs to change — and exactly wrong for anything mutable. A cache whose key does not incorporate its inputs will keep serving the first content ever stored under it, forever, with no error anywhere. ## Artifacts: outputs for people `store_artifacts` uploads files for retention and download after the run: ```yaml - store_artifacts: path: coverage destination: coverage-report ``` Artifacts are for coverage reports, binaries you want to hand to someone, logs and screenshots from a failed test. They are not automatically injected into any later job; a subsequent job wanting them would have to fetch them deliberately. Treating `store_artifacts` as the way to pass files between jobs is the third variant of the same confusion. ## Diagnosing the reported failure Work the list in order. Does the producing job actually run `persist_to_workspace`, and do the listed `paths` exist relative to `root` at that moment (a build that writes to `build/` while the config persists `dist` fails here)? Does the consuming job run `attach_workspace`, at a path its later steps actually reference? Is there a `requires` edge from consumer to producer — without one the workflow may run them concurrently? And is a cache being used where a workspace belongs, which is the version that fails intermittently rather than always, because the answer depends on what happens to be stored under that key. ## Choosing, in one line each - Cross-job files inside one run, must be exact: **workspace**. - Re-fetchable dependencies you want faster next time, correctness unaffected if absent: **cache**. - Output a human or an external system reads after the run: **artifact**.