This documentation is an FAQ / Troubleshoot for the applications (Streamlit and Reflex).
Reflex build fails with "The persisted lockfile is out of sync with the recovered package.json"
When building or running a Reflex app, the build stops with the following error:
The persisted lockfile is out of sync with the recovered package.json. Delete the
/lab/.sys/bricks//src///_/reflex.lock directory and rerun
so Reflex regenerates it from scratch.
[ShellProxy] Command failed
Why does this happen?
Reflex keeps a reflex.lock directory next to the app, holding bun.lock and a persisted package.json. Because reflex init wipes and regenerates the .web directory on every build, this directory is what preserves the resolved dependency version pins from one build to the next.
On each init, Reflex copies the persisted lockfile into .web, rebuilds .web/package.json seeded from the persisted one, then runs bun install --frozen-lockfile. The frozen flag means bun refuses to install if package.json asks for anything the lockfile cannot satisfy.
The two files are written back at different moments: the lockfile only after a successful install, the package.json after bun add resolves new packages. An interrupted build or a version bump can therefore leave package.json ahead of bun.lock. Reflex catches bun's raw error error: lockfile had changes, but lockfile is frozen and rewrites it into the message above (see _run_initial_install in reflex/utils/js_runtimes.py).
How to fix the issue?
- Delete the
reflex.lock directory named in the error message.
- Rebuild or run the app in your dev environment so Reflex regenerates the directory from scratch. This first build is slower, because the dependency tree is re-resolved without pins.
- Commit the regenerated
reflex.lock directory.
- Publish a new version of the brick, so the consistent lockfile ships with it.
Deleting the directory only fixes your own environment. The regenerated reflex.lock must be committed and published for other developers and the deployed lab to get the fix.
How to avoid it?
There is no app-side setting that prevents this drift, as Reflex has no automatic fallback to a non-frozen install for this case. The practical measure is to treat reflex.lock as a regenerable cache: when the Reflex version or an app's JS dependencies change, delete and regenerate it as part of that upgrade rather than waiting for a build to fail.
