Publish and deployment issues
A browser draft, server Save, local Publish and remote deployment are separate states. Inspect which state changed before acting again. Keep saved source and the last reviewed artifact; never use retries as a substitute for checking whether a switch landed.
The reader still looks old
| Layer | Verify |
|---|---|
| Browser | Intended buffer saved or retained |
| Server | Correct Markdown/settings/links |
| Local output | Publish/build completed and reviewed |
| Remote host | Intended artifact deployed |
| Cache | Actual response and asset versions |
Editors can Save assigned content but cannot Publish. Ask an administrator after checking the source Save outcome. Local Publish does not commit to Git, upload to a host or purge a CDN. A remote deployment success badge does not prove its deep pages, search JSON and vendor assets match the intended artifact.
Check/snapshot failures
| Message pattern | Safe next check |
|---|---|
| A publish is already running | Existing job state; do not stack jobs |
| Content folder not found | Installed content path and permissions |
| No markdown files found | Intended source tree and extensions |
| The editor cannot write to… | Output parent access and free space |
Only one job runs in the process. A busy start returns 409; monitor the current job instead of repeated clicks. Snapshot requires source and writable output parent. Temporary build/source/runtime folders are siblings of output, so permission to write inside existing dist/ alone is not enough.
Use the actual service identity and sandbox rules when checking ownership or ReadWritePaths. Do not make private runtime world-readable/writable or disable service protections merely to clear a permission symptom. Markdown and selected runtime data are snapshotted; static/templates/file config are installed inputs. Avoid changing those inputs during a release.
Build and verification failures
| Message pattern | Check |
|---|---|
| Could not start the build | Runtime/process execution |
| The build took longer than… | Timeout, workload and process |
| The build exited with code… | First relevant sanitized builder error |
| The new build is missing… | Required generated artifact |
| search-index.json…not valid JSON | Actual staged index |
| Built … of … pages | Expected versus reported count |
Default publisher timeout is five minutes. Timeout kills the child builder; it is not a request to raise limits without diagnosis. YAML/duplicate routes, input/configuration damage and filesystem failures need correction at their named source. Direct CLI build and editor Publish have different output-preservation behavior; do not extrapolate one to the other.
Verification requires home, 404, parseable search JSON and matching generated-page count. It does not certify every link, visual, private audience, browser operation or host rule. Before-switch failures normally retain old live output and saved source; inspect the report for the actual live state. Publishing stages gives the full contract.
Switch and recovery
| Message | Meaning |
|---|---|
| Could not move the live folder aside | First rename failed |
| Could not switch in the new build | Second rename failed; restoration attempted |
| Live site may be missing | Restoration did not succeed |
| Could not rotate the backup | New output may already be live |
| After the switch…is missing | Inspect live and retained prior output |
| Could not record the publish state | Output and state may disagree |
The two renames are not one atomic transaction. Requests between them can see a missing page. If the second rename fails, the publisher attempts to restore the old folder. If restoration fails, its report names where the old version remains. Do not assume a universal “nothing changed” promise after switch begins.
Before moving or deleting anything, record actual live, staged, old-aside and previous folders from the job/diagnostics and inspect their files. Preserve recoverable artifacts. Use the reviewed operator rollback procedure for your installation; generic path examples are not authority to move production output. If reported state is unclear, stop the affected release and keep the reader outage visible to the responsible operator.
A backup-rotation warning can leave the old version under an aside name while new output is live. A marker warning can make unpublished status inaccurate despite a successful switch. Inspect actual reader content before starting another job. dist.previous is one output copy, not account/source/version history.
State and history warnings
| Symptom | Check |
|---|---|
| Unpublished after CLI build | Editor marker absent/stale |
| Status reset after restart | Current job was process memory |
| History could not be written | Data permissions/free space |
| Action succeeded but event absent | Action state before repeating |
| Older activity missing | Bounded rotation/filters/cursor |
Unpublished detection uses file paths/sizes/rounded mtimes, not content hashes or remote deployment state. An equal-size/timestamp edit can evade it. CLI output may exist without an editor publication marker. Neither green nor pending status replaces an artifact review.
Audit failure does not undo an already-completed login, settings action or publish. Fix history storage separately and inspect retained records, warning state and action result. Event redaction is helpful but not a guarantee that arbitrary copied diagnostics contain no private data.
Remote deployment checks
Check the host’s intended branch, build command, output root and complete artifact. Verify home, deep route, HTTP404, search response, CSS/font/vendor/media files and any legacy redirect. Inspect status, Location/media type and actual content, not only HTTP200.
Cloudflare Pages _redirects rules are host-specific; local preview does not apply them. Functions can change which rules execute. Other hosts need their own redirects/404 configuration. Old URL map records the retained explicit rules and provider boundary.
Cache changes, rollback, DNS or external uploads are separate operator actions. Preserve the last reviewed version and verify the intended environment/audience before committing them. Finish by recording the local and remote states separately so “published” cannot mean two different outcomes.