5. When something goes wrong#

Authority for this chapter: docs/production-readiness/12_INSTALL_RUNBOOK.md section 10 (rollback for your own, still-in-progress install) and docs/production-readiness/13_RS3000_ROLLBACK.md (reverting a plant that was already live, which is not your job — see The line you never cross below).

First: which kind of problem is this?#

Before you do anything, work out which of these two situations you're in — the right response is completely different for each.

Everything else in this chapter is about situation A — something broken partway through this visit. If instead you're visiting a laptop that already has a working Ring on it and you're simply putting a newer version on top (nothing is broken; this is a planned update), that's a different job with its own steps: see chapter 2, "Putting a new version on a laptop that already has Ring".

Quick symptom table#

Collecting evidence to send to engineering#

Start on the Health tab, before you collect anything. Inside Ring, go to Setup → Password (administrator tier — see chapter 3), then Setup → Diagnostic Console…. Its Health tab shows 16 live rows in one glance — PLC endpoint and connection state, heartbeat age and poll interval, data freshness, the database's path/size/journal mode and how long since it last wrote, the config validator's status, the app version and uptime, and the single-instance check — which answers most "is it actually broken, or does it just look broken" questions faster than collecting a bundle first. Copy diagnostics text copies that Health panel, as plain text, to the clipboard — quick to paste straight into a phone call or a chat with engineering without leaving the screen.

If the Health tab doesn't answer it, collect both of these before you call — the built-in bundle is fast but not exhaustive, and engineering will sometimes ask for the other half too:

1. The built-in support bundle. Click Refresh once so the console captures a fresh snapshot, then click Collect support bundle. There is no Save dialog to answer — it always writes straight to the current user's Desktop as RingSupportBundle-<computername>-<timestamp>.zip, and the resulting message box names the exact path so you know where to find it. The bundle auto-includes the rolling application log, recent managed crash logs, native WER crash dumps (if Install-RingWerDumps.ps1 was run), a sanitized copy of the effective configuration (passwords and similar secrets replaced with ***), a fresh startup-configuration- validator report, PreflightReport.txt if one is present next to the install, a database schema/row-count census (counts only, never row data), and the last 24 hours of the PLC communication log — everything a first triage pass needs, in one file, with no folder-hunting required.
2. Fall back to collecting folders by hand only if Ring won't even launch far enough to reach the Diagnostic Console — the support bundle above already covers what step 2 used to ask you to zip manually. In that launch-failure case, gather instead:
   • %ProgramData%\Ring\logs\ (the rolling application log)
   • C:\Ring\App\logs\crashes\ (managed crash reports, if Ring's own code caught the failure)
   • C:\Ring\logs\dumps\ (native crash minidumps — only present if Install-RingWerDumps.ps1, or the one-command kiosk installer that includes it, was run; if this folder doesn't exist, that's expected and not itself a problem)
   • Your C:\Ring\App\Config\appsettings.local.json
3. The exact text of any error dialog, typed or photographed — don't paraphrase it, the exact wording is often the fastest clue.

Rolling back your own unfinished install#

This is a rollback, not an upgrade — the two are opposites and are not interchangeable. A later version's install visit (chapter 2, "Putting a new version on a laptop that already has Ring") only ever copies new files on top of a working install, and is safe by construction — the release package itself is built to exclude the database and your settings overlay, so there is nothing in it that could overwrite them. What follows here instead deletes C:\Ring\App\ outright. Use it only for situation A above — an install visit that has not yet been handed to operators. Follow it in order:

1. Stop Ring if it's still running (Task Manager → find Ring.exe → End Task).
2. Save a copy of the evidence first, so nothing is lost when you remove files in the next step — zip up %ProgramData%\Ring\logs\, C:\Ring\App\logs\crashes\, C:\Ring\App\Config\, and (if you didn't redirect it in chapter 2) C:\Ring\App\RingwoodDatabase.db, into one file somewhere outside C:\Ring\ (for example, your Desktop or a USB drive).
3. Remove the install: delete the C:\Ring\App\ folder, the **Ringwood HMI** desktop shortcut, and the Start-menu copy you created in chapter 2. Leave C:\Ring\Pictures\ and C:\Ring\Icons\ in place — they don't cause harm and save you re-copying logo files on a retry.

   Warning: If you left Database.ConnectionString at its default (chapter 2) instead of pointing it outside C:\Ring\App\, the database file lives inside the folder you're about to delete — step 2 above is the only copy of it you'll have. Confirm step 2 actually captured it before you delete anything.

4. If this laptop had a working legacy system before you started and you disabled or removed it as part of your visit, put it back per that system's own procedure — do not attempt this from memory; ask engineering if you're not certain how.
5. Send the evidence zip from step 2 to engineering, along with which numbered step in this book you were on and the exact wording of whatever failed.
6. Do not try the same install again the same day. Re-attempting with the same package on the same problem usually just repeats it and makes the eventual diagnosis harder, not easier.

The line you never cross#

Whatever the symptom, and whoever is asking on the phone, do not do any of the following yourself:

• Never turn read-only mode off. That is the formally-scheduled cutover, run by Ringwood's own engineers against a signed-off checklist — never a troubleshooting step, never something to try "just to see."
• Never touch the PLC or controller directly — no forcing values, no changing its program, nothing. Ring's own job is to never do this either outside a supervised, signed-off cutover; yours is the same.
• Never hand-edit any file beyond exactly what this book told you to create or fill in (appsettings.local.json, and nothing else). A file you don't recognize is not yours to open and change.
• Never run the plant-wide legacy-system rollback procedure yourself. That is 13_RS3000_ROLLBACK.md, and it exists specifically because it needs an engineer's judgment about a live, already-operating plant — a different situation from the one this book covers.
• Never keep retrying the same failed step over and over. If the quick table and one attempt at its fix don't resolve it, that's the signal to collect evidence and call, not to try five more times.

You are done when…#

• You have correctly identified whether you're in situation A or situation B above.
• For situation A: either the problem is fixed and Checks 1-12 in chapter 4 all pass, or you've rolled back cleanly and sent engineering the evidence they need.
• For situation B: you've made the phone call and stopped — this was never yours to fix.

Next: 6. Install record and pre-drive checklist.