From dd14ca1f2fb243619954dc26f73c730dddae399c Mon Sep 17 00:00:00 2001 From: Georges-Antoine Assi Date: Sat, 18 Jul 2026 08:05:36 -0400 Subject: [PATCH 1/2] docs: document TrueNAS cross-dataset artwork issue RomM can't link ROMs to their artwork when the library and resources volumes live on different ZFS datasets, even with correct permissions and art downloading fine. Add a troubleshooting entry with the fix. Generated-By: PostHog Code Task-Id: f91b5297-525b-418d-9e5d-ec18e94360ec --- docs/install/truenas.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/install/truenas.md b/docs/install/truenas.md index b32db7fa..d8d490f5 100644 --- a/docs/install/truenas.md +++ b/docs/install/truenas.md @@ -73,6 +73,30 @@ Save, and you're done! If you're seeing permission errors on paths _inside_ the container (not on TrueNAS datasets), try temporarily running the container as root (`user: 0`) to unblock yourself, fix the offending permissions via shell, and switch back to a non-root user. In at least one reported setup, creating a user/group in TrueNAS with UID/GID `1000:1000` and the auxiliary `apps` group was needed to get the app talking to its embedded Valkey cleanly. +### Artwork/covers download but never show up + +If a scan reports success and the logs show art being fetched (and you can even see the downloaded media on disk), but covers and artwork stay blank in the UI, check whether your **Library** and **Assets/resources** volumes live on **different ZFS datasets**. + +RomM can't link ROMs to their artwork across dataset boundaries, even when permissions are correct on both. This most often happens when ROMs sit on a media/game dataset while resources are pointed at a Docker-specific dataset. + +The fix is to keep the library and resources on the **same dataset**. For example, this works: + +```yaml +volumes: + - /mnt/Tank1/games/roms:/romm/library + - /mnt/Tank1/games/resources:/romm/resources +``` + +while this leaves artwork unlinked, even though the art downloads correctly: + +```yaml +volumes: + - /mnt/Tank1/games/roms:/romm/library + - /mnt/Tank1/Docker/resources:/romm/resources +``` + +Keeping just the database and config file on a separate Docker dataset is fine — only the library and resources need to share a dataset. + ### Other issues - [Scanning Troubleshooting](../troubleshooting/scanning.md) for matching/ingest problems From 246924826d77d32c8aae7d61634fb3a88207ef53 Mon Sep 17 00:00:00 2001 From: Georges-Antoine Assi Date: Sat, 18 Jul 2026 14:49:09 -0400 Subject: [PATCH 2/2] run fmt --- docs/install/truenas.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/install/truenas.md b/docs/install/truenas.md index d8d490f5..3f04a1c0 100644 --- a/docs/install/truenas.md +++ b/docs/install/truenas.md @@ -83,16 +83,16 @@ The fix is to keep the library and resources on the **same dataset**. For exampl ```yaml volumes: - - /mnt/Tank1/games/roms:/romm/library - - /mnt/Tank1/games/resources:/romm/resources + - /mnt/Tank1/games/roms:/romm/library + - /mnt/Tank1/games/resources:/romm/resources ``` while this leaves artwork unlinked, even though the art downloads correctly: ```yaml volumes: - - /mnt/Tank1/games/roms:/romm/library - - /mnt/Tank1/Docker/resources:/romm/resources + - /mnt/Tank1/games/roms:/romm/library + - /mnt/Tank1/Docker/resources:/romm/resources ``` Keeping just the database and config file on a separate Docker dataset is fine — only the library and resources need to share a dataset.