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 catalogue

• 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 catalogue shows it when it exists.

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.

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.

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.

A banner says Moonbase is running on default settings

The plugin's configuration file was reset, usually after a crash mid-write, but a backup with your real settings is still on disk. Click Restore these settings on the Actions tab, then restart the server. Nothing user-side is affected. 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.

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.