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.
• 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.
• 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.
• Enable Moonbase Sync on the General tab must be on. Without it the app sees the plugin but can't use it.
• In the app, Settings > Integrations > Moonbase Plugin needs Enable Plugin ticked.

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, Seerr URL filled in, and Enable Moonbase Sync on the General tab.
• 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.

The step-by-step page is Seerr Setup.

Seerr notifications never arrive

• Check the provisioning status next to Public Server URL 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 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.

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, ratings sources can be toggled under Settings > Integrations > Metadata & Ratings.
• 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.
• Rows arrive switched off. Users turn them on under Settings > Personalization > Home Screen > Home Row Toggles, or you set a default on the Defaults tab.
• Rows are cached on the server and refresh on the task schedule. Running the task by hand forces 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.

Anime filler or recap badges don't appear

• Anime markers are Jellyfin only. Tick Classify anime episodes as canon, mixed or filler on the Integrations tab 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. It 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, 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 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.

On Jellyfin, 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. 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.

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 General > 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.