Fix reed build failing with a missing or stale prefetch

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):

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

1
[reed] the store at "<store>" was prefetched for a different scaffoldDependencies pin set (stale prefetch) — run `reed prefetch`.
2
[reed] the store at "<store>" was prefetched with pnpm <old>, but this build is pinned to pnpm <new> — run `reed prefetch`.
3
[reed] the store at "<store>" was prefetched for darwin/arm64, but this machine is linux/x64 — run `reed prefetch` on this machine.
4
[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).
5
[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:

1
[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:

1
reed prefetch
2
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:

1
npm install -g corepack
2
corepack enable pnpm
3
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:

1
export REED_STORE_DIR="$PWD/.ci-cache/reed-pnpm-store"
2
export COREPACK_HOME="$PWD/.ci-cache/corepack"
3
export REED_COREPACK_HOME="$COREPACK_HOME"
4
reed check
5
if [ "$REED_CACHE_HIT" != "true" ]; then
6
  reed prefetch
7
fi
8
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 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:

1
reed build --out dist; echo "exit $?"
2
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.

reed prefetch
Environment variables
Offline builds in CI — a full GitHub Actions setup
Quickstart — installing Corepack on Node 25+