---
title: Fix reed build failing with a missing or stale prefetch
description: build and dev install offline from the store reed prefetch fills. Re-run prefetch, and cache both directories in CI.
---

## Symptom

`reed build` or `reed dev` fails before any page is rendered, with a message that names
`reed prefetch`. Reed checks the store before it installs anything and says which
precondition failed. These are the messages, verbatim from Reed's source (`build failed:`
is the CLI's prefix):

```txt
build failed: [reed] no prior prefetch found at "/home/me/.reed/pnpm-store" — run `reed prefetch`.
```

```txt
[reed] the store at "<store>" was prefetched for a different scaffoldDependencies pin set (stale prefetch) — run `reed prefetch`.
[reed] the store at "<store>" was prefetched with pnpm <old>, but this build is pinned to pnpm <new> — run `reed prefetch`.
[reed] the store at "<store>" was prefetched for darwin/arm64, but this machine is linux/x64 — run `reed prefetch` on this machine.
[reed] the pinned pnpm@<version> binary was never cached by Corepack on this machine — run `reed prefetch` (which populates both the dependency store and Corepack's binary cache).
[reed] Corepack is required but not available on this machine — install/enable Corepack, then run `reed prefetch`.
```

The last case to recognise passes every marker check and still fails inside pnpm. Reed
wraps pnpm's own output:

```txt
[reed] the store at "<store>" matched this invocation's pins, but the offline install still failed (exit 1) — the store contents may be corrupted or incomplete; run `reed prefetch` to repopulate it. Underlying pnpm output:
```

One real example, seen on a developer machine: the underlying output was
`ERR_PNPM_NO_MATCHING_VERSION` for `@oxc-project/types@=0.150.0`, a package version the
store did not hold. It stopped the moment `reed prefetch` was re-run.

## Cause

`reed build` and `reed dev` never download dependencies. They install the site
generator's pinned dependencies with `pnpm install --offline` from a local store, and the
only thing that fills that store is `reed prefetch` — the one Reed command that touches
the network. `prefetch` writes a marker recording the pin set, the pnpm version, and the
platform, architecture and libc it ran on. A build compares that marker with itself and
refuses to continue on any mismatch, rather than silently reaching the network.

So the store is missing or stale when:

- `reed prefetch` never ran on this machine, or ran with a different `REED_STORE_DIR`;
- you upgraded Reed and the new version pins different dependencies or a different pnpm;
- the store was copied from another OS, architecture, or libc (glibc and musl are
  different targets);
- a CI job restored only one of the two caches `prefetch` fills.

Once a project's dependencies are installed, Reed caches them under `.reed/` and skips
the install on later builds. That is why this failure tends to appear on a fresh clone, a
new CI runner, or right after an upgrade — not in the middle of a working session.

`reed check` never needs a prefetch. It is a read-only validation pass and never runs the
install step, so a passing `check` says nothing about whether the store is ready.

## Fix

### Re-run prefetch

On the machine that failed, with network access:

```sh
reed prefetch
reed build --out dist
```

One prefetch serves every Reed project on the machine; it takes no `--dir`.

### Make sure Corepack exists

`prefetch`, `build` and `dev` run pnpm through Corepack. Node 25 and newer no longer bundle
Corepack, so on those versions install it before prefetching:

```sh
npm install -g corepack
corepack enable pnpm
reed prefetch
```

Or use Node 22 or 24, which still ship it.

### Point every command at the same caches

`prefetch` fills two separate caches:

| Variable | Default | Holds |
|---|---|---|
| `REED_STORE_DIR` | `~/.reed/pnpm-store` | the pinned dependency store |
| `COREPACK_HOME` / `REED_COREPACK_HOME` | Corepack's own default | the pinned pnpm binary |

If you set any of these, set them identically for `prefetch` and for `build`. A store
written to one path and read from another is "no prior prefetch" as far as the build can
tell.

### In CI, restore both caches

Cache and restore **both** directories, keyed on something that changes when Reed's pins
do. Run `reed prefetch` after the restore only when the exact key missed, on a step that
has network access. `REED_CACHE_HIT` below stands for whatever your CI reports; on GitHub
Actions it is `steps.<id>.outputs.cache-hit`:

```sh
export REED_STORE_DIR="$PWD/.ci-cache/reed-pnpm-store"
export COREPACK_HOME="$PWD/.ci-cache/corepack"
export REED_COREPACK_HOME="$COREPACK_HOME"
reed check
if [ "$REED_CACHE_HIT" != "true" ]; then
  reed prefetch
fi
reed build --out dist
```

A stale store on a cache hit is not silent: `reed build` stops and tells you to run
`reed prefetch`. See [Offline builds in CI](/docs/ship/ci-offline) for a full
GitHub Actions setup.

Restoring only one cache still builds on a networked runner while quietly fetching the
other, and then fails on the first runner without egress. Run `prefetch` once per
platform your pipeline uses.

## Verify

Run the build and confirm it exits zero without a pipe hiding the status:

```sh
reed build --out dist; echo "exit $?"
ls "${REED_STORE_DIR:-$HOME/.reed/pnpm-store}/.reed-prefetch.json"
```

The marker file exists and the build prints no `[reed] ... run reed prefetch` line. To
prove the build is genuinely offline, run it once inside a sandbox with no network — see
[Offline builds in CI](/docs/ship/ci-offline).

## Related

- [reed prefetch](/docs/reference/cli/prefetch)
- [Environment variables](/docs/reference/env)
- [Offline builds in CI](/docs/ship/ci-offline) — a full GitHub Actions setup
- [Quickstart](/docs/quickstart) — installing Corepack on Node 25+