Update Troubleshooting
Settings → Updates doesn’t show a release that exists
Section titled “Settings → Updates doesn’t show a release that exists”- The check is cached for up to 6 hours.
pnpm run updatedoesn’t depend on it and always sees the newest release. - Only Admins and Owners see version information.
- “Checking for new releases is turned off” means
UPDATE_CHECK_REPO = "off"inwrangler.toml. - “Couldn’t check for a newer release right now” means GitHub couldn’t be reached; it retries within the hour.
See how the update check works.
“Already up to date”, but a change I expected isn’t there
Section titled ““Already up to date”, but a change I expected isn’t there”pnpm run update installs releases only. A fix or feature that has been merged but not released yet arrives with the next release; check the Changelog for what each release contains. To try unreleased code on a test install, use pnpm run update -- --branch develop.
An install that followed a branch before is ahead of the latest release, and also reports “Already up to date” until a release catches up with it. That is expected.
“There is no release vX.Y.Z”
Section titled ““There is no release vX.Y.Z””The version given to --version doesn’t exist. Check the releases page and pass the number without the v: pnpm run update -- --version 0.9.1.
“This install is on vX, newer than vY. pnpm run update doesn’t downgrade”
Section titled ““This install is on vX, newer than vY. pnpm run update doesn’t downgrade””--version named a release older than the one you run. Updates only move forwards, because database migrations don’t run backwards. To really go back, see Rolling back.
“Merging vX.Y.Z hit a real conflict”
Section titled ““Merging vX.Y.Z hit a real conflict””Your project has edits to files that the release also changed. Nothing was deployed. Run git status to see the conflicting files, resolve them (keep your change, the release’s, or combine them) and commit. If the update said your local config changes were stashed, bring them back with git stash pop. Then run pnpm run update again. If you didn’t mean to keep local edits to CMS files, git merge --abort (then git stash pop if needed) returns to where you were.
“Restoring your local config changes hit a conflict”
Section titled ““Restoring your local config changes hit a conflict””The update stashes your uncommitted changes (usually wrangler.toml) before merging and restores them afterwards. Here the release changed the same lines. Your changes are still in the stash: resolve the conflict shown by git status, drop the stash with git stash drop once your values are back, and run pnpm run update again.
“Run pnpm run setup first” / wrangler.toml has no database_id
Section titled ““Run pnpm run setup first” / wrangler.toml has no database_id”Either setup never finished, or a merge overwrote the value. Check git log -p -- wrangler.toml for a merge commit that replaced your real database_id, bucket_name, BETTER_AUTH_URL or custom-domain routes with the template’s placeholders, and restore them from the commit before it. Do not run setup to recover: it would provision new resources instead of finding the old ones.
Update refuses to redeploy: Worker belongs to a different deployment
Section titled “Update refuses to redeploy: Worker belongs to a different deployment”A Worker of the same name in your Cloudflare account is bound to a different D1 database. Every fork ships the same default Worker name, so one account running several deployments can collide, and wrangler deploy would silently overwrite the other one. Run pnpm run setup and choose a new Worker name when prompted. If you really renamed this install’s Worker on purpose, update name in wrangler.toml to match.
Unrelated histories
Section titled “Unrelated histories”Installs scaffolded before the switch to a real git clone need one confirmed reconciliation merge. pnpm run update explains it and asks first, and restores wrangler.toml to what you had committed just before the merge.
No upstream remote
Section titled “No upstream remote”Update skips the code pull with a note and redeploys what is on disk. To opt back in:
git remote add upstream https://github.com/kenresoft-technologies/kenresoft-cms.gitAdmin looks broken right after an update
Section titled “Admin looks broken right after an update”Cloudflare’s edge cache may briefly serve the old admin index.html, which references a previous bundle. Wait a few minutes and hard-refresh. The deploy did not fail.
A configuration flag did not update code
Section titled “A configuration flag did not update code”pnpm run update -- --auth, --email, --domain and the others change configuration only. They do not pull code, install dependencies or run migrations. Run the plain pnpm run update for that. See Update the CMS.
Astro site did not change
Section titled “Astro site did not change”pnpm run update never updates a website. Use npx @kenresoft-cms/create astro --update in it.