fix(saves): tell the setup wizard a 404 is an answer, not an outage

get_save_setup_info collapsed every server-saves failure onto
recommended_action "server_unreachable", so a RomM database reset — which
drops this device's registration and makes the saves query 404 — told the
user their server was offline while it was answering fine.

Add a fourth arm, "not_found", peeled off with a sibling
except RommNotFoundError. It holds the wizard exactly as the unreachable
branch does: a 404 leaves the server's slot inventory just as unproven as an
outage, so auto-confirming the default slot could still clobber real server
saves on the first post-confirmation sync. The launch gate likewise still
aborts. Only the copy and the reachability verdict change.

The copy deliberately does not say the game has no saves. The 404 can come
from the device registration rather than the ROM, so that would swap one lie
for a more specific one; it states what RomM could not find instead.

SlotSetupWizard needed no change: it already tested for an explicit
server_unreachable, so a not_found result now correctly reports the server
reachable and leaves the reconnect gate disarmed.

This clears the last site flagged by check_404_not_unreachable.py.

Author: danielcopper

docs/user-guide/troubleshooting.md

@@ -85,6 +85,13 @@ the RomM database was reset and this device's registration disappeared with it 
 **RomM offline** badge stays clear and the surface tells you what's missing instead. If you see such a message while the
 badge is clear, the fix is on the RomM side (re-sync the library, or re-check the game), not with your network.
 
+The first-time save-slot setup screen is the clearest example. If RomM can't find the save data that setup needs, it
+pauses with "RomM couldn't find the save data for this setup" rather than the "server is not reachable" message, and the
+offline badge stays clear. Setup deliberately stops there instead of picking a slot for you: the plugin has no
+trustworthy view of what's on the server, and choosing a slot on that basis could overwrite real saves on the first
+sync. Re-check the game in RomM (or, after a server database reset, reconnect in the plugin's Connection settings so
+this device is registered again), then tap **Retry**.
+
 ### Save file not found
 
 **Symptom**: The game detail page shows save status but no save file is being synced.

py_modules/services/saves/slots/setup.py

@@ -18,7 +18,7 @@
 from domain.rom_save_sync_state import RomSaveSyncState
 from domain.save_layout import SAVE_SYNC_CONTENT_DIR_REASON
 from domain.save_slot import save_in_slot
-from lib.errors import classify_error
+from lib.errors import RommNotFoundError, classify_error
 from services.saves._helpers import newest_server_saves_by_target
 from services.saves._messages import (
     DEVICE_NOT_REGISTERED_REASON,
@@ -96,11 +96,45 @@ def is_save_tracking_configured(self, rom_id: int) -> dict[str, Any]:
         active_slot = game_state.active_slot if (game_state and configured) else None
         return {"configured": configured, "active_slot": active_slot}
 
+    def _setup_query_failed(
+        self,
+        *,
+        local_files: list[dict[str, Any]],
+        local_file_info: list[dict[str, Any]],
+        game_state: RomSaveSyncState | None,
+        default_slot: str,
+        recommended_action: str,
+    ) -> dict[str, Any]:
+        """Build the held-wizard payload for a failed server-saves query.
+
+        Every failure branch holds the wizard the same way — an unproven
+        server view must never auto-confirm the default slot, whatever the
+        cause. Only *recommended_action* differs, so the frontend can say
+        why without claiming the server is offline.
+        """
+        slot_confirmed = bool(game_state.slot_confirmed) if game_state else False
+        return {
+            "has_local_saves": len(local_files) > 0,
+            "local_files": local_file_info,
+            "server_slots": [],
+            "default_slot": default_slot,
+            "slot_confirmed": slot_confirmed,
+            "active_slot": game_state.active_slot if (game_state and slot_confirmed) else None,
+            "recommended_action": recommended_action,
+            "server_query_failed": True,
+        }
+
     async def get_save_setup_info(self, rom_id: int) -> dict[str, Any]:
         """Get info needed for the first-sync setup wizard.
 
         Fetches server saves, checks local files, determines which
         scenario (A-E) applies so the frontend can display the right UI.
+
+        ``recommended_action`` carries the failure cause when the server-saves
+        query raises: ``server_unreachable`` for a transport failure,
+        ``not_found`` when the server answered that it has no such ROM or
+        device id. Both hold the wizard identically — only the copy and the
+        frontend's reachability verdict differ (#1570).
         """
         rom_id = int(rom_id)
 
@@ -126,22 +160,36 @@ async def get_save_setup_info(self, rom_id: int) -> dict[str, Any]:
                     lambda: self._romm_api.list_saves(rom_id, device_id=device_id),
                 ),
             )
+        except RommNotFoundError as e:
+            # The server ANSWERED — it has no such ROM, or no such device id
+            # (#1560's shape: a RomM database wipe drops this device's
+            # registration). Reporting that as "unreachable" sends the user to
+            # check a connection that is plainly working, so it gets its own
+            # recommendation. The wizard still HOLDS: a 404 leaves the server's
+            # slot inventory just as unproven as an outage does, so
+            # auto-confirming the default slot could still clobber real server
+            # saves on the first post-confirmation sync.
+            self._logger.warning(
+                f"get_save_setup_info({rom_id}): server has no such rom or device: {e}",
+            )
+            return self._setup_query_failed(
+                local_files=local_files,
+                local_file_info=local_file_info,
+                game_state=game_state,
+                default_slot=default_slot,
+                recommended_action="not_found",
+            )
         except Exception as e:
             self._logger.warning(
                 f"get_save_setup_info({rom_id}): failed to list server saves: {e}",
             )
-            slot_confirmed = bool(game_state.slot_confirmed) if game_state else False
-            active_slot = game_state.active_slot if (game_state and slot_confirmed) else None
-            return {
-                "has_local_saves": len(local_files) > 0,
-                "local_files": local_file_info,
-                "server_slots": [],
-                "default_slot": default_slot,
-                "slot_confirmed": slot_confirmed,
-                "active_slot": active_slot,
-                "recommended_action": "server_unreachable",
-                "server_query_failed": True,
-            }
+            return self._setup_query_failed(
+                local_files=local_files,
+                local_file_info=local_file_info,
+                game_state=game_state,
+                default_slot=default_slot,
+                recommended_action="server_unreachable",
+            )
 
         # Group server saves by slot
         slots_map: dict[str | None, list[dict[str, Any]]] = {}

src/components/SlotSetupWizard.test.tsx

@@ -1116,6 +1116,47 @@ describe("SlotSetupWizard", () => {
       expect(getRommConnectionState()).toBe("offline");
     });
 
+    it("does NOT report offline when the load returns recommended_action=not_found", async () => {
+      // #1560's path: the 404 means the server ANSWERED. Reporting offline
+      // here blacked out the whole UI while RomM was working fine (#1570).
+      setRommConnectionState("checking");
+      vi.mocked(backend.getSaveSetupInfo).mockResolvedValue(
+        makeSetupInfo({ recommended_action: "not_found", server_query_failed: true }),
+      );
+      const result = makeSetupInfo({ recommended_action: "not_found", server_query_failed: true });
+      vi.mocked(backend.getSaveSetupInfo).mockResolvedValue(result);
+      render(<SlotSetupWizard {...defaultProps()} />);
+      await flushAsync();
+
+      // Post-load state: the store went CONNECTED (the server answered), and
+      // the result was still routed into the hold path rather than short-
+      // circuiting. The banner copy itself is covered in saveSetup.test.ts —
+      // this file stubs applyWizardInitialSetupResult.
+      expect(getRommConnectionState()).toBe("connected");
+      expect(vi.mocked(applyWizardInitialSetupResult)).toHaveBeenCalledWith(result, expect.anything());
+    });
+
+    it("leaves the reconnect gate disarmed after a not_found load", async () => {
+      // offlineHeldRef must stay false: there is no connection to wait for, so
+      // a later →connected edge must not trigger a re-fetch loop (#1570).
+      setRommConnectionState("checking");
+      vi.mocked(backend.getSaveSetupInfo).mockResolvedValue(
+        makeSetupInfo({ recommended_action: "not_found", server_query_failed: true }),
+      );
+      render(<SlotSetupWizard {...defaultProps({ romId: 9 })} />);
+      await flushAsync();
+      const callsAfterLoad = vi.mocked(backend.getSaveSetupInfo).mock.calls.length;
+
+      await act(async () => {
+        setRommConnectionState("offline");
+        reportServerReachable(true);
+        await Promise.resolve();
+      });
+      await flushAsync();
+
+      expect(vi.mocked(backend.getSaveSetupInfo).mock.calls.length).toBe(callsAfterLoad);
+    });
+
     it("auto-reloads on reconnect after holding the offline error", async () => {
       setRommConnectionState("offline");
       render(<SlotSetupWizard {...defaultProps({ romId: 5 })} />);

src/components/SlotSetupWizard.tsx

@@ -518,6 +518,10 @@ function useSaveSetupInfo(romId: number, onComplete: () => void) {
         // definitive offline signal; any other resolved result proves the
         // server answered. A throw is a bridge/unknown error, not a verdict —
         // the catch leaves the store untouched.
+        // Only an explicit unreachable verdict means offline. A `not_found`
+        // result PROVES the server answered, so it reports reachable and
+        // leaves the reconnect gate disarmed — the wizard still holds, it
+        // just doesn't wait for a connection that was never lost (#1570).
         const reachable = result.recommended_action !== "server_unreachable";
         reportServerReachable(reachable);
         offlineHeldRef.current = !reachable;
@@ -576,6 +580,10 @@ function useSaveSetupInfo(romId: number, onComplete: () => void) {
         // Same conservative feed as the initial load (#1345): the manual
         // Retry re-probes reachability, so a server_unreachable result
         // re-arms offline and any other result reports the server back.
+        // Only an explicit unreachable verdict means offline. A `not_found`
+        // result PROVES the server answered, so it reports reachable and
+        // leaves the reconnect gate disarmed — the wizard still holds, it
+        // just doesn't wait for a connection that was never lost (#1570).
         const reachable = result.recommended_action !== "server_unreachable";
         reportServerReachable(reachable);
         offlineHeldRef.current = !reachable;

src/types/saves.ts

@@ -174,10 +174,12 @@ export interface SaveSetupInfo {
   // "server_unreachable" means the server-saves fetch failed — the wizard MUST
   // hold and offer a retry instead of treating the empty server_slots as
   // authoritative (auto-confirming default would clobber real server saves on
-  // first sync). See backend `get_save_setup_info`.
-  recommended_action: "auto_confirm_default" | "show_wizard" | "server_unreachable";
-  // Mirrors recommended_action === "server_unreachable" — explicit flag for
-  // call sites that route on the boolean rather than the enum.
+  // first sync). "not_found" is the same hold for a different cause: the
+  // server ANSWERED that it has no such ROM or device id, so the wizard must
+  // not report the server offline (#1570). See backend `get_save_setup_info`.
+  recommended_action: "auto_confirm_default" | "show_wizard" | "server_unreachable" | "not_found";
+  // True whenever the server-saves query failed, whichever way — an explicit
+  // flag for call sites that route on the boolean rather than the enum.
   server_query_failed?: boolean;
 }
 

src/utils/saveSetup.test.ts

@@ -12,6 +12,8 @@ import {
   wizardMigrationOutcomeToastBody,
   SERVER_UNREACHABLE_WIZARD_MESSAGE,
   SERVER_UNREACHABLE_TOAST_BODY,
+  NOT_FOUND_WIZARD_MESSAGE,
+  NOT_FOUND_TOAST_BODY,
   type LaunchGateSetupDeps,
   type SaveSetupOutcome,
   type WizardRetryDeps,
@@ -45,6 +47,25 @@ describe("resolveSaveSetupOutcome", () => {
     expect(resolveSaveSetupOutcome(info)).toEqual({ kind: "server_unreachable" });
   });
 
+  it("routes 'not_found' to its own outcome, NOT to auto-confirm", () => {
+    // The empty server_slots is no more authoritative on a 404 than on an
+    // outage, so this must not fall through to the auto-confirm branch (#1570).
+    const info = makeInfo({ recommended_action: "not_found", server_query_failed: true });
+    expect(resolveSaveSetupOutcome(info)).toEqual({ kind: "not_found" });
+  });
+
+  it("routes 'not_found' even with local saves and an empty server list present", () => {
+    // The exact shape that would otherwise auto-confirm under 'show_wizard'.
+    const info = makeInfo({
+      recommended_action: "not_found",
+      has_local_saves: true,
+      server_slots: [],
+      default_slot: "default",
+    });
+    expect(resolveSaveSetupOutcome(info)).not.toEqual({ kind: "auto_confirm", slot: "default" });
+    expect(resolveSaveSetupOutcome(info)).toEqual({ kind: "not_found" });
+  });
+
   it("routes 'auto_confirm_default' to the auto-confirm outcome with the default slot", () => {
     const info = makeInfo({ recommended_action: "auto_confirm_default", default_slot: "main" });
     expect(resolveSaveSetupOutcome(info)).toEqual({ kind: "auto_confirm", slot: "main" });
@@ -95,6 +116,17 @@ describe("applyLaunchGateSetupOutcome", () => {
     expect(deps.confirmSlotChoice).not.toHaveBeenCalled();
   });
 
+  it("aborts the launch on not_found too, with its own copy", async () => {
+    // The launch must NOT proceed with save tracking unconfigured just
+    // because the failure was a 404 rather than an outage (#1570).
+    const deps = makeLaunchGateDeps();
+    const result = await applyLaunchGateSetupOutcome({ kind: "not_found" }, deps);
+    expect(result).toBe("abort");
+    expect(deps.toast).toHaveBeenCalledWith(NOT_FOUND_TOAST_BODY);
+    expect(deps.dispatchSavesTab).toHaveBeenCalledOnce();
+    expect(deps.confirmSlotChoice).not.toHaveBeenCalled();
+  });
+
   it("calls confirmSlotChoice with the resolved slot and proceeds on auto_confirm", async () => {
     const deps = makeLaunchGateDeps();
     const outcome: SaveSetupOutcome = { kind: "auto_confirm", slot: "main" };
@@ -190,6 +222,27 @@ describe("applyWizardInitialSetupResult", () => {
     expect(deps.onComplete).not.toHaveBeenCalled();
   });
 
+  it("sets the not-found banner and bails, never auto-confirming", async () => {
+    // Same hold as server_unreachable — the wizard must not configure a slot
+    // against an unproven server view just because the cause was a 404 (#1570).
+    const deps = makeWizardDeps();
+    const result = makeInfo({ recommended_action: "not_found", server_query_failed: true });
+    await applyWizardInitialSetupResult(result, deps);
+    expect(deps.setError).toHaveBeenCalledWith(NOT_FOUND_WIZARD_MESSAGE);
+    expect(deps.setConfirming).not.toHaveBeenCalled();
+    expect(deps.confirmSlotChoice).not.toHaveBeenCalled();
+    expect(deps.setInfo).not.toHaveBeenCalled();
+    expect(deps.onComplete).not.toHaveBeenCalled();
+  });
+
+  it("the not-found copy names what RomM could not find, not that saves are absent", () => {
+    // The 404 can come from the DEVICE registration, so claiming the game has
+    // no saves would swap one lie for a more specific one (#1570).
+    expect(NOT_FOUND_WIZARD_MESSAGE).not.toMatch(/no saves|has no save|without saves/i);
+    expect(NOT_FOUND_WIZARD_MESSAGE).not.toMatch(/unreachable|not reachable|offline/i);
+    expect(NOT_FOUND_TOAST_BODY).not.toMatch(/unreachable|not reachable|offline/i);
+  });
+
   it("auto-confirms and calls onComplete on 'auto_confirm_default'", async () => {
     const deps = makeWizardDeps();
     const result = makeInfo({ recommended_action: "auto_confirm_default", default_slot: "alpha" });
@@ -292,6 +345,15 @@ describe("applyWizardRetrySetupResult", () => {
     expect(deps.setInfo).not.toHaveBeenCalled();
   });
 
+  it("sets the not-found banner and clears loading on 'not_found'", () => {
+    const deps = makeRetryDeps();
+    const result = makeInfo({ recommended_action: "not_found" });
+    applyWizardRetrySetupResult(result, deps);
+    expect(deps.setError).toHaveBeenCalledWith(NOT_FOUND_WIZARD_MESSAGE);
+    expect(deps.setLoading).toHaveBeenCalledWith(false);
+    expect(deps.setInfo).not.toHaveBeenCalled();
+  });
+
   it("sets the fetched info and clears loading on a non-unreachable result", () => {
     const deps = makeRetryDeps();
     const result = makeInfo({ recommended_action: "show_wizard" });