Back to Explore
GuideVibeFix editorialUpdated Nov 20, 2026

Downtime Without the Drama: Maintenance Mode That Users Can Actually Tolerate

Maintenance mode is a whole mechanism, not a static page: three tiers, four sentences of copy, a one-page rollback plan, and a rehearsed recovery. A practical guide with a worked 132-minute window.

A developer working late at night in front of multiple screens of code (real photo)

Maintenance mode is not "put up a page and call it done"

Every vibe-coded project eventually reaches this day: the database needs migrating, a core dependency needs upgrading, the billing system needs replacing — in short, the service has to stop for a while. When that happens, what should users see when they open your product? Is one line of "under maintenance, come back later" enough? Far from it.

Maintenance mode is a whole mechanism: how far in advance to announce, whether users can still read old data while you work, how write operations get blocked, what the maintenance page says, how you verify after recovery, and how you roll back if things go sideways. Hanging up a single static page just pushes every user question during maintenance onto support and social media. This guide is about turning maintenance mode into a complete, rehearsed process. The example product "Skylark Notes" and the person "Xiao-Yu" are fictional, used only to illustrate the flow, and the numbers are sample calculations.

Draw the line first: planned maintenance, surprise outages, and read-only mode are three different things

Before building, separate three concepts that are easy to confuse. Planned maintenance is downtime you schedule: you pick the time, you pick the scope, users know in advance. A surprise outage is downtime you did not plan: the service is down, you are fixing it, users are waiting. The first tests your preparation, the second tests your response. Their copy, process, and postmortems are all different — do not share one script for both.

Read-only mode is a third state: the service is up, but writes are temporarily off. Users can read, search, and export, but cannot create, edit, or delete. For many products, read-only mode is better than taking the whole site down: reads usually account for more than 80% of traffic, and keeping reads alive keeps most of the experience alive. Skylark Notes' rule is to prefer read-only mode for migration work, and only go fully offline when the underlying storage itself changes so much that even reads cannot be guaranteed.

One more boundary: maintenance mode versus the status page. The status page broadcasts "what state the service is in right now"; maintenance mode is the mechanism inside the product that decides "how to respond right now." Before maintenance, the status page posts the announcement; during maintenance, it updates progress; after maintenance, it posts the recovery notice. The status page talks; maintenance mode acts. A status page guide already exists on this site, so this article covers only the "acting" part, with the division of labor stated up front.

Three tiers of maintenance: pick by impact, do not take the whole site down by default

Maintenance mode should come in three tiers, chosen by impact from smallest to largest. Tier one is "feature-level maintenance": only one feature goes offline, everything else works normally. If the payment module needs an upgrade, close just the payment entry point and say on the page: "Payments are under maintenance, expected back in 30 minutes; everything else works normally." Most user actions are unaffected, and churn stays minimal.

Tier two is "read-only mode": the whole site is readable but not writable. Users can open docs, search, and export; a write action shows a clear message: "Saving is temporarily unavailable during maintenance. Your content is saved locally and will sync automatically after recovery." The key sentence is the one about local saving: content the user is writing must not be lost — losing it is an incident. The technical points of read-only mode get their own section below.

Tier three is "full shutdown": every request returns the maintenance page. This is the heaviest tier, reserved for two situations: the underlying storage or auth system itself is changing and reads cannot be guaranteed, or compliance requires a full stop. If tier one solves it, do not use tier two; if tier two solves it, do not use tier three. The heavier the tier, the more users you lose and the more recovery verification costs.

The choice of tier should live in the maintenance handbook, not be debated in a meeting each time. Skylark Notes' handbook has a decision table: changing one service means tier one; touching the database with reads still guaranteed means tier two; touching the database with reads not guaranteed means tier three; touching auth or billing defaults to tier three. The table is pinned at the top of the team docs, so a new hire can follow it on day one.

Maintenance page copy: four sentences, none optional

The maintenance page is the only thing users see during maintenance, and its copy deserves real attention. A good maintenance page needs just four sentences — but not one of them can be missing.

Sentence one: say what is happening. "Skylark Notes is undergoing planned maintenance." Do not write vague words like "system upgrade" — users have no idea which "system" you mean. Say clearly that it is planned maintenance, not an outage: planned downtime and a failure feel completely different to users. One says "they are doing work," the other says "something broke."

Sentence two: say what is affected. "During maintenance you can view existing content, but cannot create or edit for now." What users care about most is "what can I still do," not what you are fixing. Be specific about which features are affected — do not write uselessly correct phrases like "some features are unavailable."

Sentence three: say when it will be back. "Expected back within 2 hours and 30 minutes, no later than 4 hours." Give two numbers: the expected time and the latest time. Give only the expected time and users feel lied to when it slips; give only the latest time and users think you have no confidence. Give both and users know where they stand. Write times in the user's own timezone — writing UTC times is the same as writing nothing.

Sentence four: give users somewhere to go. "See the status page for the latest updates" with a link, or "For urgent issues contact support" with an email address. During maintenance, users do not stop needing help — they just do not need to bother engineers. Putting the status page link and a support email on the maintenance page gives them a path that does not involve calling anyone.

Two things must never appear. Do not write template politeness like "we apologize for any inconvenience" — it only irritates people more. Do not write technical details such as "migrating PostgreSQL 15 to 16" — users do not care, but competitors will be very interested. Technical details belong in the internal postmortem, not on the public page.

How read-only mode actually works: three technical points

Read-only mode sounds simple but has three technical points that must be handled properly. The first is where writes get blocked. The right approach is to intercept all write requests in one place — at the gateway or middleware layer — returning a clear maintenance status code and message, instead of checking inside every endpoint. Centralized blocking cannot miss an endpoint: any new endpoint behind the gateway is blocked automatically. Checks scattered across endpoints will eventually miss one, letting a user write a row during maintenance that no longer reconciles after recovery.

The second is local caching and post-recovery sync. Content the user is editing gets blocked when they hit save — and that content must not be lost. The approach: the frontend writes unsaved content to local storage (localStorage or IndexedDB), the maintenance page tells the user clearly that "your content is saved locally," and after recovery it syncs automatically, with a light confirmation on success and a clear error with a manual copy-out option on failure. That chain must be tested in rehearsal, not assumed from reasoning.

The third is scheduled jobs and background writes. Many products have background jobs writing data: stats aggregation, email sending, billing runs. During maintenance those jobs must either pause or be explicitly marked as "skipped during maintenance." The most dangerous state is a half-stop: the frontend blocks users while background jobs keep writing to the database, and halfway through the migration the numbers stop adding up. Skylark Notes' practice is a "background job list" made before maintenance starts, with each item marked pause or continue and an owner for checking, verified one by one after recovery.

Timeline: how a 132-minute maintenance window actually runs

Below is a sample timeline from Skylark Notes' documented process (a fictional example, used only to illustrate the flow and the calculation method): a planned window of 150 minutes, actually completed in 132 minutes.

T-7 days: publish the maintenance announcement. It goes in three places: an in-product banner, the status page, and email. It states the maintenance date, start time (in the user's timezone), expected duration, affected scope, and what changes after recovery. Seven days' notice gives heavy users time to adjust their work rhythm. Once the announcement is out, the support team receives a Q&A sheet with prepared standard replies.

T-1 day: send a reminder. It goes only to users active in the past 30 days, repeating the key facts: maintenance starts tomorrow at midnight, expected 2 hours and 30 minutes. The goal is to lift the share of users who know about the maintenance from around 40% at announcement time to above 80%. Skylark Notes' sample data shows that only 38% of active users had opened the announcement on the day it went out, and that number rose to 79% after the reminder.

T-0, midnight: switch on read-only mode. First flip the traffic switch, then confirm all write operations are blocked, and only then start touching data. The order cannot be reversed: touch data first and block writes second, and the writes that slip through in between become dirty data. After switching on, the on-call engineer runs a smoke check: open the homepage, open a doc, attempt a write and confirm it is blocked correctly, and glance at the monitoring dashboard.

Midnight to 2:12 a.m.: migration and verification. This is the real work. After the migration script finishes, do not restore service immediately — run verification first: are the row counts right, can sampled content be opened, are key endpoints' latencies normal? Skylark Notes' rule is that every item on the verification checklist must be ticked before recovery begins; if any item fails, follow the rollback plan. The rollback plan is not something you invent on the spot — it is written and rehearsed before maintenance starts.

2:12 a.m.: restore service. The order is: switch maintenance mode off first, then reopen writes, then remove the in-product banner. The first thing after restoring is the recovery notice: update the status page, swap the banner to "Maintenance complete, thank you for waiting." The notice should state the actual time used — 132 minutes, 18 minutes ahead of the planned 150 — because finishing early is good news worth sharing.

T+1 day: postmortem. The meeting answers four questions: how far was actual time from planned time, and why; were there user complaints, and what did they cluster around; did any verification checklist item get waved through; and what should change next time? The notes go to the whole team, with no blame, only process changes. Skylark Notes' postmortem template is one page — when the page is full, stop. No long essays.

A maintenance window timeline: T-7 days announcement → T-1 day reminder → T-0 midnight read-only on → 132 minutes of migration and verification → recovery → T+1 day postmortem

The rollback plan: the one page that must be written before maintenance starts

What maintenance fears most is not slowness but being unable to go back. The rollback plan answers one question: if something goes wrong halfway, how do you return to the pre-maintenance state in the shortest possible time?

The plan fits on one page but must contain five elements. First, trigger conditions: when to start a rollback — data validation fails, core endpoint error rates pass a threshold, the migration script errors and cannot be diagnosed within 15 minutes. Triggers must be specific enough — "roll back if things look wrong" means something different to everyone. Second, rollback steps: in order, each with the command or entry point, the expected result, and who executes it. Third, the backup point: when the backup was taken, where it lives, and how long restoring takes. Fourth, notification templates: once the rollback decision is made, what the status page and in-product banner say, so users learn immediately that "maintenance is extended, we are rolling back, expected recovery at this time." Fifth, the decision-maker: who has the authority to order a rollback — at 2 a.m. nobody votes in a meeting; one person decides.

Skylark Notes has a real rollback story (as an example): the migration script errored at 70% progress, and the on-call engineer rolled back to the backup point within 12 minutes following the plan. Total downtime was 96 minutes — 24 minutes over plan — but with zero data loss. The postmortem conclusion was that a rollback plan's value is not in "never using it" but in "not having to invent it when you need it."

Three things after recovery: verify, notify, observe

Restoring service does not end maintenance — three things remain. First, verify, item by item, not by feel. The checklist should cover at least five items: can core pages open, can writes save normally, are search and export working, are payment and billing flows alive, and have error rates on the monitoring dashboard returned to baseline? Skylark Notes requires two people to cross-check: one executes, one reviews, and both sign the list. One person verifying alone is how items get waved through; two people watching each other makes that much less likely.

Second, notify. The recovery notice goes everywhere the announcement went: the in-product banner becomes "Maintenance complete," the status page updates to "Recovered." No need for another email — recovery emails have very low open rates and are just one more disturbance. The notice should say three things: maintenance is complete, how long it actually took, and where to go if something looks wrong. If actual time beat the plan, say so — it is evidence you keep your word. If it ran over, say so honestly, with one sentence on why, instead of pretending it did not happen.

Third, observe. The 24 hours after recovery are the high-risk window: data problems from the migration often do not explode immediately, but surface when users gradually reach the affected features. Keep the on-call rota running for 24 hours after recovery, tighten alert thresholds one notch for the first 6 hours, and investigate any anomaly as "probably maintenance-related" first. Skylark Notes learned this the hard way once: everything looked fine after recovery, and six hours later a rarely used export feature turned out to be missing a column — because the verification checklist had not covered it. Since then the checklist includes sampling every export and stats feature touching the migrated tables.

Pre-launch checklist: tick every box before maintenance starts

Before maintenance begins, check each item on this list. Announcements: the T-7 day announcement is out in all three places (in-product, status page, email); the T-1 day reminder is sent; the support Q&A sheet is synced. Technical: the backup is done and verified restorable; the migration script has run clean in staging; the rollback plan is printed next to the duty roster; the write-block switch has been tested; the background job list has its pause items confirmed. Duty: the rota is set with primary and backup on-call both online; the decision-maker is confirmed; the monitoring dashboard is open; comms channels (group chat, phone) are tested. User-facing: the four sentences on the maintenance page are checked; times are written in the user's timezone; the status page link and support email work.

One check is most often forgotten: the first wave of traffic after recovery. The instant service returns, a flood of users refresh at once and retry their saves, and the traffic peak can be three to five times normal. If the backend collapses right after recovering, the maintenance was wasted. The fix: restore to 10% of traffic first, watch for 5 minutes, confirm latency and error rates are normal, then open fully. That gradual restore belongs in the maintenance handbook, not left to the on-call engineer's improvisation.

Summary

Maintenance mode is, at its core, about turning "downtime" — a bad thing — into something users can understand, expect, and tolerate. That takes four things, not one maintenance page: tiered modes (feature-level, read-only, full shutdown, chosen by impact); four sentences of copy (what happened, who is affected, when it returns, where to follow up); a written rollback plan (triggers, steps, backup point, notification templates, decision-maker); and a rehearsed recovery flow (gradual traffic restore, verification checklist, postmortem notes). Skylark Notes' sample timeline planned 150 minutes and finished in 132, restoring 18 minutes early. Remember one principle: during maintenance, what users fear most is not waiting — it is not knowing how long the wait is or what is happening. Give them enough information, and the wait becomes much easier to bear.

Views 4Comments 0

Comments (0)

ME
0/1000
Loading comments...
Browse projectsPublish your project

Related articles

Screenshot of Amp's new thread composer: the run-location picker lists Boxes, and the acme/workbench workspace shows the bug-tracker, tiny-crm, team-wiki and incident-database apps
News
An $18-a-Month Home for Agent-Built Software: Amp's Boxes Fill In the Last Missing Piece

On 10 November 2026, Amp launched Boxes: always-on mini-computers from $18 a month for deploying software you built with an agent. Each box runs its own runner, so the agent can edit live production data right there; the same month Amp also shipped Spaces, retired the Dial, and arrived on Windows — the agent's workplace is moving off the laptop into the cloud.

Developer WorkflowProduct LaunchDeployment
Real photo: a bank of light gray metal filing cabinets with one drawer pulled open, revealing rows of hanging file folders inside
Guide
A real database inside the browser: IndexedDB local storage, explained plainly

localStorage only stores strings and has no indexes. IndexedDB is a real database in the browser: structured data, far larger capacity, indexes, and transactions. Following MDN's Using IndexedDB, IDBDatabase, and IDBObjectStore: the five-step routine, opening, upgrades, keys, indexes, transactions, add versus put, get, cursors, ranges, and multi-tab upgrades.

Tool TipsData WorkflowsFrontend Engineering
Real photo: hands typing on a MacBook Pro showing JavaScript code that changes HTML content, with a white mouse, papers, and binders on a white desk
Guide
Functions without the confusion: JavaScript functions, parameters, and arrow functions, explained plainly

You already call functions every day; this guide names what you have been doing. Following MDN's Functions, Arrow function expressions, and Rest parameters: declarations versus expressions, parameters and arguments, default values, rest parameters, spread syntax, return values, arrow function shorthand, the this trap, callbacks, and scope.

Tool TipsFrontend EngineeringAI Coding