Some of the most frustrating website failures start with a successful operation. The content is in the database. The publish call returns success. The homepage loads. Then a linked article returns a 404.
The missing check is often the template
On an Umbraco site, a document is more than its fields. Its renderable page also depends on the template associated with its document type. A full-replacement update that leaves the template out can quietly remove that association. The node still exists, and navigation can still point at it, but the public request has nothing to render.
That is why “the API returned 200” is not a sufficient migration test. It tells you that the write was accepted. It does not tell you that the page is still renderable.
Our post-migration smoke test
- Read before writing. Fetch the current document and preserve its complete shape, including the template and variants.
- Change only what you intend to change. For a title or body update, use a property-level update where possible. If a full replacement is unavoidable, merge the change into the document you read.
- Publish the node. A draft is not evidence that the public route works.
- Fetch the exact public URL. Check for a 200 response, the expected page title, and a distinctive piece of the new content.
- Check the supporting assets. A healthy homepage does not prove that static files, scripts, or stylesheets survived a backend change.
Why this matters beyond Umbraco
The same pattern appears in migrations, imports, and infrastructure cutovers: a system can be internally consistent and still be externally broken. Verify the thing a visitor needs, not only the operation that an API reports.
For us, the useful habit is simple: read, make the smallest safe change, publish, and test the real URL with real content. It takes less time than explaining a mysterious 404 after launch.