Common Problems

Common Problems

Plain fixes for the things server admins run into most with Moonbase. Try the steps in order. The last section says what to send if none of them help.

Moonbase doesn't show up in the Jellyfin catalog

• The repository URL must be exactly https://raw.githubusercontent.com/Moonfin-Client/Plugin/refs/heads/master/manifest.json. A trailing space or a copy of the GitHub page URL instead of the raw file won't work.
• Your Jellyfin must be 10.10 or newer. Older servers hide plugins built for a newer version.
• Switch to another dashboard page and back to Catalog, or restart Jellyfin, to make it re-read the repositories.
• The server needs internet access to reach GitHub. Some Docker setups block outbound traffic.

The plugin shows as Malfunctioned, Disabled or Not Supported

• Malfunctioned usually means the plugin was built for a different Jellyfin version than the one running. Update Jellyfin, or install the Moonbase version whose target matches. Dashboard > Logs shows the exact error next to "Moonfin".
• Disabled: click the plugin in My Plugins and choose Enable, then restart.
• A hand-installed copy on Linux can fail on file permissions. Make the plugins/Moonfin folder readable by the Jellyfin user.
• After a big Jellyfin upgrade, wait for a Moonbase release that targets it. The catalog shows it when it exists.

Moonbase disappeared after a restart

When a plugin fails to start, Jellyfin marks it as malfunctioning and deletes its folder on the next start. Older Moonbase versions could fail that way when their settings file couldn't be read, so it looked like Moonbase had uninstalled itself. Current versions keep loading even then.

• Reinstall Moonbase from the catalog and restart Jellyfin.
• Your users' settings, Seerr sessions, themes and saves are still there, since they live in a separate Moonfin folder. See Data Locations.
• If the plugin page comes back with its settings empty, see Server settings came back as defaults.

The web app at /Moonfin/Web/ is blank or gives 404

• Jellyfin: run the Moonfin Startup task under Dashboard > Scheduled Tasks, then hard refresh the browser (Ctrl+F5, or Cmd+Shift+R on a Mac).
• Emby: the web folder must sit next to Emby.Plugins.Moonfin.dll in the plugins folder. A zip extracted into a subfolder puts it in the wrong place.
• Silo and Plex: a Moonbase build without the web app answers 404 here. On Silo, open it from Plugin Apps > Moonfin. On Plex, it's on Moonbase's own port, http://<host>:32500/Moonfin/Web/.
• Behind a reverse proxy: the proxy must forward every /Moonfin/ path. If http://<server ip>:8096/Moonfin/Web/ works on the local network but the public address doesn't, that's the cause. See Reverse Proxy and Seerr.
• Make sure you typed the path with the capital letters, /Moonfin/Web/, and a trailing slash.
• Jellyfin, still a 404: search the log for web app is not on disk. That warning names the folders Moonbase looked in. Reinstalling the plugin puts the files back.

The Moonfin button is missing from Jellyfin's header

• The button needs the File Transformation plugin. Install it, restart Jellyfin, then force refresh the browser (Ctrl+F5, or Cmd+Shift+R on a Mac). The steps are on Installation.
• Run the Moonfin Startup task once under Dashboard > Scheduled Tasks and refresh again.
• The button sits next to your user icon, on Jellyfin 12's header too. If it only goes missing on Jellyfin 12, update Moonbase. Older versions didn't place it there.
• Check Branding > Custom CSS for the .headerMoonfinButton rule that hides it.
• Clicking a Jellyfin Enhanced button opens Moonfin Web instead, the Calendar for example: update Moonbase. Jellyfin Enhanced puts its buttons in whatever sits before your user icon, which used to be the Moonfin button, so its buttons ended up inside ours. The Moonfin button now sits in Jellyfin's own header button row.
• Emby has no header button. Open /Moonfin/Web/ directly.

Apps say "This server does not have the Moonfin plugin installed"

• Check the plugin is Active in the dashboard and the server was restarted after installing.
• The app must be connected to an address that reaches the plugin. A reverse proxy that only forwards some paths, or a tunnel that rewrites them, hides /Moonfin/ from the app while the rest of Jellyfin works.
• Moonbase Sync, at the top of the User defaults tab, must be on. Without it the app sees the plugin but can't use it.
• In the app, Settings > Account > Settings Sync should say Connected, with sync on.

Settings don't follow me to another device

• Sync is per user. Both devices must be signed in as the same server user, with Enable Plugin on in both apps.
• Some settings are meant to differ. Moonbase keeps a global profile plus optional overrides for desktop, mobile and TV, so a choice made on the TV can be a TV-only override. Settings Sync explains the layering.
• One user's settings file can be damaged after a crash. Run Moonfin Settings File Repair under Scheduled Tasks. Anything it can't fix goes to a quarantine folder rather than being deleted. See Data Locations.

Seerr is missing from the apps, or sign-in fails

• Integrations tab: Enable Seerr ticked and Seerr URL filled in. Moonbase Sync at the top of the User defaults tab has to be on too.

• The Seerr URL must be reachable from the server, not just from your PC. In Docker, localhost points at the wrong container. Use the LAN address or the container name.

• For Jellyfin sign-in to work, Seerr has to have imported that Jellyfin user. Ask whoever runs Seerr to add them.

• Browsing works but requests fail: the user lacks request permission inside Seerr.

• One user sees almost nothing in Seerr: they have a parental limit. Moonbase leaves out titles above it, and unrated ones, using each title's rating on TMDB. Without a TMDB key, the server-wide one or the user's own, nothing can be checked and that user sees nothing at all, so set a Server-wide TMDB API Key on the Integrations tab.

The step-by-step page is Seerr Setup.

Seerr notifications never arrive

• Check the webhook provisioning status under Seerr Integration on the Integrations tab. If it says a foreign webhook is in the way, Seerr's single webhook slot is used by something else.
• Seerr has to be able to reach your server. Set Public Server URL on the Web Client tab to an address Seerr can hit, for example http://192.168.1.10:8096, then click Re-provision webhook.
• Only users who have signed in to Seerr through a Moonfin app at least once can be notified.
• The full checklist is on Seerr Notifications.

Android phones never get push notifications

If no push ever reaches an Android phone, Seerr notifications and party alerts alike, while the in-app banners still show, check the DNS blocklist on that network, such as Pi-hole, AdGuard Home or Technitium. A blocklist that blocks firebaseinstallations.googleapis.com stops the phone from ever getting a push token, so the server has nowhere to send to. Allowlist that name, then close Moonfin fully and open it again so it registers.

Ratings from MDBList or TMDB don't appear

• Paste a Server-wide MDBList API Key (and a TMDB API Key for episode ratings) on the Integrations tab and Save.
• Run Moonfin MDBList Ratings Sync under Scheduled Tasks once. Ratings are fetched in batches, so a big library takes a while on the first run.
• In the apps, rating sources are picked under Settings > Appearance > Details Page > Rating Sources, and Home Screen and its Media Bar page each have their own Ratings section.
• A free MDBList key has a daily request limit. A very large library may need a second day to finish.

IMDb, MDBList or custom rows don't show on the home screen

• Tick Sync IMDb charts or Sync MDBList official lists on the Integrations tab, then run the matching sync task.
• On Plex there's no sync task. Moonbase for Plex fetches a list the first time an app asks for it and keeps it for a day.
• Users turn them on under Settings > Appearance > Home Screen > Rows. The admin page has no default for these rows anymore, since the apps offer each one whenever the server can fill it.
• Rows are cached on the server and refresh on the task schedule. Running the task by hand forces it.
• Empty or short rows for a user with a parental limit. Custom rows are filtered by the user's parental rating limit, using the age rating TMDB has for each title, and under a limit a title with no known rating is left out. Without any TMDB key, that's every MDBList, IMDb and Letterboxd title. Paste a Server-wide TMDB API Key on the Integrations tab.
• A big MDBList list never loads. Update Moonbase and the app. A list of 450 or so items took longer to resolve than the app waited, and the server threw the work away when the app gave up. The app now waits longer, and on Jellyfin the server finishes the work in the background so the next load gets it.

Ratings, rows or logos only update when I run the task by hand

Older Moonbase versions left their scheduled tasks without a schedule on Jellyfin 10.11 and 12, so they only ran when started by hand. Update Moonbase and restart. Open any Moonfin task under Dashboard > Scheduled Tasks and it should list at least one trigger. If one still has none, add a daily trigger yourself.

The seasonal row is empty or missing

• Users turn it on in their apps under Settings > Appearance > Home Screen > Rows. It's off by default, and there's no admin default for it. Its country and holidays are under Seasonal Row on the same page.
• It only shows during a holiday window, such as all of October for Halloween or the day after US Thanksgiving through December 26 for Christmas, unless the user turned on Show All Year. Lunar New Year, Diwali and Thanksgiving only show in the countries that celebrate them, going by the country the app sends or your server's metadata country.
• On Emby, paste a Server-wide TMDB API Key on the Integrations tab and run Moonfin Seasonal Keywords Sync under Scheduled Tasks. Emby doesn't store TMDB keywords, so until that task has run no owned movie can match a holiday.
• On Jellyfin, owned movies match through the keyword tags Jellyfin's TMDB provider writes. A movie without those tags still matches once the TMDB key is set and the same task has run, as long as it has a TMDB id.
• No suggestions? They need Seerr set up, the user signed in to Seerr, and a TMDB key.
• A user with a parental limit doesn't see unrated titles in the row.

Smart Search rows don't show up

• Smart Search only runs for searches of two words or more. One word uses the normal search.
• Check that Enable smart search is ticked on the Smart Search tab and saved, then restart the apps. They check whether it's on when they start.
• The first build, or the rebuild after switching the Search model, may still be running. Look at Moonfin Smart Search Index under Dashboard > Scheduled Tasks. Until the library part is done, searches only show the normal results. On a Raspberry Pi that can take a while, see Smart Search.
• No Smart Search on Seerr row? It needs the server-wide TMDB key on the Integrations tab and Seerr turned on, and it fills in after the TMDB catalog is built, which takes longer than the library.
• If the task fails right away, check the server log for lines starting with Smart search. The server needs to reach huggingface.co to download the model the first time.

The Calendar button is missing, or the calendar won't load

• On Jellyfin and Emby the calendar needs Seerr turned on, Sonarr and Radarr added in Seerr, and one Seerr admin signed in to Seerr through a Moonfin app. On Plex it needs Sonarr or Radarr set on the Moonbase for Plex admin page.
• Who can see the calendar set to Admins only hides it from everyone else.
• "An admin needs to sign in to Seerr in Moonfin before the calendar can load" means no Seerr admin has a stored session yet.

Each message the apps show is explained on Calendar.

Someone forgot their PIN or is locked out

Open the Accounts tab and use Change PIN or Remove PIN on that user. An admin doesn't need the old PIN, and setting a new one also clears the wrong-guess count. After five wrong guesses each new try waits 30 seconds longer, up to 15 minutes, and the wait survives a server restart, so restarting doesn't help.

Anime filler or recap badges don't appear

• Tick Classify anime episodes as canon, mixed or filler on the Labels tab, under Anime episodes, and Save.
• Run Moonfin Anime Markers Sync under Scheduled Tasks, or type the show into Preview a series and press Fetch now. The nightly task stops after 45 minutes, so a big library takes a few nights to get through.
• Press Check matching. A series that matched nothing either isn't on AnimeFillerList or goes by a different title there. When your library's title doesn't match, Moonbase also tries the English and romaji titles AniList has for the series' provider ids, so make sure the series has its AniList, MyAnimeList, TVDB, TMDB or IMDb id. A series that still matches nothing can't get filler badges, but Subbed and Dubbed pills still work for it.
• The canon pills are off by default. Tick Manga canon or Anime canon under Which pills to show if you want them.
• Subbed and Dubbed need a language tag on the audio tracks. Untagged audio is left unmarked.
• Still missing? Turn on Write a marker debug log, open the show in the app, then press Show log. If the request isn't there, the app never asked, and the problem is on the app side.

Games don't show up

• Enable retro games on the Games tab, and tick the right Game libraries.
• Folders inside the library must be named per system, one folder per console, using the names on Retro Games.
• Admins can open https://<server>/Moonfin/Games/Debug in a browser while signed in. It lists what the plugin sees: whether games are enabled, which libraries are configured and whether their folders exist.
• On Smart TVs, games need webOS 5 or Tizen 5 and newer. Apple TV and iPhone play a fixed set of systems.

PSP games won't start in the web app

PSP games need the web app to be cross-origin isolated. On Jellyfin or Emby, tick Isolate the web app for PSP games on the Games tab, Save, then reload Moonfin Web. If you've added anything cross-origin to the web client, it has to allow isolation too.

Server settings came back as defaults

When Jellyfin or Emby can't read a plugin's settings file, it quietly writes a fresh one with default values over it. From your side, everything on the Moonbase page is simply gone after a restart: API keys, Seerr, defaults and messages. Older Moonbase versions could cause this themselves when a message or theme name held characters the file can't store, like an emoji cut in half. Current versions strip those out before saving, but a full disk or a hand-edited file can still do it.

Moonbase keeps a spare copy of the file and refreshes it at every startup, as long as the settings aren't all defaults. After a reset:

1. Open the Moonbase page. An amber banner at the top says These settings look like they were reset.
2. Click Restore these settings.
3. Restart the server. The restored settings only take effect after a restart.

The server log also has a warning naming the backup. To restore by hand, stop the server, copy plugins/configurations/Moonfin/config-backup/Moonfin.Server.xml over plugins/configurations/Moonfin.Server.xml, and start it again. On Emby both files are named Emby.Plugins.Moonfin.xml. No banner means there's no backup to go back to, so the settings have to be entered again. Nothing user-side is affected either way. User settings live in separate files.

Server settings wiped after a catalog update

This one comes from two copies of Moonbase loading at the same time. Jellyfin empties the settings file while it starts the second copy. The dashboard still shows a single Moonbase as Active, so nothing looks wrong.

It happens when a hand-installed copy of 2.2.0 or older sits next to a newer one from the catalog. Jellyfin normally retires the old folder after a catalog update, but it can't when the plugins folder is read-only, as with NixOS and other declarative setups. In that case it happens again on every restart.

1. Look in Jellyfin's plugins folder for two Moonbase folders, for example Moonfin or Moonbase next to Moonbase_2.4.0.0.
2. Stop the server and delete the older folder.
3. If you have your own backup of plugins/configurations/Moonfin.Server.xml, copy it back. The restore banner can't help with this one, because Moonbase refreshed its spare copy after the file was already emptied. Without a backup, the settings have to be entered again.
4. Start the server.

On a read-only setup, update Moonbase by replacing its folder rather than from the catalog. User settings live in separate files and aren't affected.

Where the logs are

• Jellyfin: Dashboard > Logs, open the newest file and search for Moonfin or Moonbase.
• Emby: Dashboard > Logs, same search.
• A user's app can also send its own report to the server. That's covered on each client's Collecting Logs page, for example the Moonfin app and the Smart TV app. On Emby this needs Enable client log upload under Help > Diagnostics, which is on by default. Reports show up as upload_<client>_<version>_<time>.txt.
• The anime marker debug log, when it's turned on, is moonfin-anime-markers.log in the same list.

Still stuck

Open a GitHub issue with:

• Jellyfin or Emby, and its version
• The Moonbase version (shown on the plugin page)
• Whether a reverse proxy or Docker is involved
• The log lines mentioning Moonfin from around the time it failed

For quick questions, GitHub Discussions or the Discord.