Merge pull request #3544 from rommapp/fix/crash-on-startup-no-library

fix: Crash on startup when no library

Author: zurdi15

backend/handler/filesystem/platforms_handler.py

@@ -4,10 +4,8 @@
 
 from config import LIBRARY_BASE_PATH
 from config.config_manager import config_manager as cm
-from exceptions.fs_exceptions import (
-    FolderStructureNotMatchException,
-    PlatformAlreadyExistsException,
-)
+from exceptions.fs_exceptions import PlatformAlreadyExistsException
+from logger.logger import log
 
 from .base_handler import FSHandler, LibraryStructure
 
@@ -59,9 +57,9 @@ def get_platforms_directory(self) -> str:
         cnfg = cm.get_config()
 
         # Fallback to config hint when detection is inconclusive: default to
-        # Structure A (roms/{platform}) so a malformed library fails loudly
-        # (FolderStructureNotMatchException) rather than treating the bare
-        # library root as a flat list of platforms.
+        # Structure A (roms/{platform}) so the bare library root is not treated
+        # as a flat list of platforms. When the roms folder is missing entirely,
+        # get_platforms() bootstraps it instead of failing.
         return "" if cnfg.has_structure_path_b else cnfg.ROMS_FOLDER_NAME
 
     def get_platform_fs_structure(self, fs_slug: str) -> str:
@@ -90,15 +88,31 @@ async def add_platform(self, fs_slug: str) -> None:
     async def get_platforms(self) -> list[str]:
         """Retrieves all platforms from the filesystem.
 
+        If no library structure exists yet (neither Structure A's top-level roms
+        folder nor a Structure B {platform}/roms folder), defaults to Structure A
+        by creating the roms folder and returns an empty list, so RomM starts
+        cleanly with an empty library instead of failing.
+
         Returns:
             List of platform slugs.
         """
         cnfg = cm.get_config()
 
         try:
             platforms = await self.list_directories(path=self.get_platforms_directory())
-        except FileNotFoundError as e:
-            raise FolderStructureNotMatchException() from e
+        except FileNotFoundError:
+            # The platforms directory does not exist, which means no library
+            # structure has been set up yet. Bootstrap Structure A so the
+            # filesystem is in a valid state and report an empty library.
+            log.warning(
+                "No library structure found; creating default Structure A "
+                "(roms folder) and starting with an empty library."
+            )
+            try:
+                self.create_library_structure()
+            except OSError:
+                log.error("Failed to create default library structure", exc_info=True)
+            return []
 
         # For Structure B, only include directories that have a roms subfolder
         structure = self.detect_library_structure()

backend/tests/handler/filesystem/test_platforms_handler.py

@@ -229,6 +229,48 @@ async def test_get_platforms_calls_list_directories_with_empty_path(
                 await handler.get_platforms()
                 mock_list.assert_called_once_with(path="")
 
+    async def test_get_platforms_bootstraps_structure_a_when_none_detected(
+        self, handler: FSPlatformsHandler, config
+    ):
+        """When no structure exists, get_platforms creates Structure A (roms folder)
+        and returns an empty list instead of raising."""
+        config.has_structure_path_a = False
+        config.has_structure_path_b = False
+        with patch(
+            "handler.filesystem.platforms_handler.cm.get_config", return_value=config
+        ):
+            with patch.object(
+                handler, "list_directories", side_effect=FileNotFoundError
+            ):
+                with patch.object(handler, "create_library_structure") as mock_create:
+                    result = await handler.get_platforms()
+
+                    assert result == []
+                    mock_create.assert_called_once()
+
+    async def test_get_platforms_returns_empty_when_bootstrap_fails(
+        self, handler: FSPlatformsHandler, config
+    ):
+        """If creating the default structure fails, get_platforms still returns an
+        empty list rather than propagating the error (so the heartbeat stays healthy).
+        """
+        config.has_structure_path_a = False
+        config.has_structure_path_b = False
+        with patch(
+            "handler.filesystem.platforms_handler.cm.get_config", return_value=config
+        ):
+            with patch.object(
+                handler, "list_directories", side_effect=FileNotFoundError
+            ):
+                with patch.object(
+                    handler,
+                    "create_library_structure",
+                    side_effect=PermissionError("read-only filesystem"),
+                ):
+                    result = await handler.get_platforms()
+
+                    assert result == []
+
     def test_integration_with_base_handler_methods(self, handler: FSPlatformsHandler):
         """Test that FSPlatformsHandler properly inherits from FSHandler"""
         # Test that handler has base methods

pyproject.toml

@@ -136,7 +136,9 @@ DEP002 = [ # DEP002 rule: Project should not contain unused dependencies
 [tool.uv]
 package = false
 exclude-newer = "7 days"
-exclude-newer-package = { starlette = "2026-05-22" }
+# vcrpy < 8.2.0 references aiohttp.streams.AsyncStreamReaderMixin, removed in
+# aiohttp 3.14; allow the fixed release past the global 7-day window.
+exclude-newer-package = { starlette = "2026-05-22", vcrpy = "2026-06-17" }
 
 [tool.ty.environment]
 root = ["./backend"]