Common Problems

Common Problems

Plain fixes for the things people ask about most. Try the steps in order. If none of them help, the last section tells you what to send so someone can look into it.

Can't connect to the server

1. Open the address in a web browser on the same device. If the browser can't reach it either, the address or the network is the problem, not Moonfin.
2. Are you on the same Wi-Fi as the server? Addresses like 192.168.x.x, 10.x.x.x or a plain name like mynas only work at home. Away from home you need an address the server owner set up for outside access, or a VPN into your home.
3. Check the port. Moonfin tries 8096 and 8920 by itself. If the server uses another port, type it after the address, like mynas:8000.
4. Turn off VPN apps and private DNS on the phone for a moment. They often block home network addresses.
5. https with a home-made certificate is often refused. On your home network use the plain http:// address, or ask the server owner for a proper certificate.
6. Is the server actually running? Restart it, and check its firewall allows the port.

Login failed

• Usernames and passwords are case sensitive. Try signing in on the server's web page with the same details.
• After several wrong attempts the server locks the account for a while. An admin can unlock it under the server's user settings.
• Quick Connect codes expire after a few minutes. Ask for a new one, and enter it on a device that is already signed in to the same server. If it says Quick Connect is disabled, an admin turns it on in the Jellyfin Dashboard > General.

Video is blurry, stutters, or the server gets loud

When your device can't play a file as it is, the server converts it on the fly. That is called transcoding. It makes the server work hard, can look softer, and stutters if the server can't keep up. Moonfin plays files untouched whenever it can, so transcoding means something in the chain said no.

Usual reasons and what to do:

Reason	Fix
Slow Wi-Fi to the TV or phone	Use a network cable on the TV, or move the router. A 4K file needs a steady, fast connection
A quality limit is set	Look for a quality or bitrate limit under Playback & SyncPlay > Video Playback Preferences and raise it
The audio track is something the device can't play	Pick another audio track in the player, or set up passthrough if you have a receiver (next section)
Image-based subtitles (PGS, VobSub) on some platforms	Choose a text subtitle track (SRT) instead, or download one from the item's page
Dolby Vision Profile 7 files on Android TV	Playback & SyncPlay > Video Playback Preferences > Dolby Vision Profile 7 direct play. Auto is the right choice for most devices
The file format is unusual (WMV, AVI)	The server remuxes these. Nothing to do on the client

To see what actually happened: on desktop press I during playback for the stream information. On any platform, turn on logging (Settings > About > Diagnostics & Logging), play the item again, and the report names who declined direct play and why.

No sound, or no sound on some movies

• Playing through the TV's own speakers: TVs can't play DTS or TrueHD. Moonfin normally converts those to something the TV understands. If a film is silent, go to Playback & SyncPlay > Audio Preferences and set Passthrough to Auto or Disabled.
• A soundbar or AV receiver over HDMI (Android TV, Apple TV): set Passthrough to Auto. If Auto guesses wrong for your receiver, choose Manual and tick only the formats the receiver supports.
• Apple TV: also check the Apple TV's own Settings > Video and Audio > Audio Format.
• Sound out of sync: the player has an audio delay control. Small offsets are normally the TV's processing, try the TV's game or PC picture mode.

Subtitles missing, wrong, or ugly

• Pick the track in the player: the subtitles button, or C on a keyboard. Off means none is selected.
• Language and when subtitles show by default live under Playback & SyncPlay > Subtitle Preferences.
• Size, font, colour and background are under Subtitle Preferences > Subtitle Customization. HDR films can have their own style there.
• No suitable track? Open the movie or episode page, find the Subtitles section, and tap the download icon. This needs the OpenSubtitles plugin on the server.
• Subtitles from a file with the same name as the video appear only if the server picked them up. Rescan the library on the server.

Dolby Vision or HDR looks green, purple, washed out or too dark

• Android TV: set Playback & SyncPlay > Video Playback Preferences > Dolby Vision Profile 7 direct play to Auto. If the colours are still wrong on that one file, set it to Disabled and let the server handle it.
• Check the TV's HDMI input is set to its enhanced or deep colour mode, and the HDMI cable is rated for 4K HDR.
• Some boxes only output HDR when the TV's picture mode allows it. Try another picture mode.

Black screen or crash when the app starts

• Android and Android TV: clear the app's storage (Settings > Apps > Moonfin > Storage > Clear storage), open it, and sign in again.
• Linux: install the xdg-user-dirs package, and if you used the tar.gz, install mpv (libmpv) too.
• Windows: update the graphics driver from the GPU maker's website.
• If it keeps happening, collect a log (see the end of this page) right after it fails.

Home screen is empty or rows are missing

• Rows can be switched off. Check Personalization > Home Screen > Home Sections and Home Row Toggles.
• A library can be hidden under Personalization > Libraries > Library Visibility.
• Pull down to refresh, or use Retry Home Rows when it appears.
• If a whole server's rows are gone, tap your avatar and check the server is still connected.

Downloads won't start, or disappeared

• On Android TV the download buttons are off until you turn on Personalization > Navigation > Show Downloads Button.
• Check free space, and the folder under Playback & SyncPlay > Offline Downloads > Download Location.
• A download in a smaller quality waits for the server to convert the file first. The Downloads screen shows the server's progress before the first byte arrives.
• On iPhone, downloads live inside the app. Offloading or deleting the app removes them.
• Fire TV and Apple TV can't download at all. See Downloads.

My TV or speaker doesn't show up when casting

• The phone and the TV must be on the same network. Guest Wi-Fi and some mesh systems keep devices apart.
• Google Cast devices show on Android and desktop. AirPlay only works from an iPhone, iPad or Mac. DLNA needs the receiver's DLNA or media renderer function switched on.
• Remote Playback (playing on another Jellyfin app) only lists devices that are signed in to the same server and currently open.

A controller or remote does nothing in the menus

• Turn on Personalization > General Style > Gamepad navigation to move around the app with a controller.
• For controllers inside games, see Retro Games. The mapping screen has a test panel that shows what the app receives.

A title shows "4K - Deleted" but the 4K file plays fine

Moonfin shows what Seerr reports, and Seerr tracks HD and 4K as two separate states. A title marked available in HD and deleted in 4K renders exactly as that badge. The usual cause is one Radarr added to Seerr twice, once as the normal server and once as the 4K server, where the 4K entry lost its 4K flag.

To fix it, open Seerr's Radarr settings and confirm the entry you use for 4K is still marked as a 4K server, set it back if not, and rescan. Seerr advises against adding the same Radarr twice. Tracked upstream as seerr#2953.

The app says an update is available but nothing happens

• Store installs update through their store. Open Google Play, the Amazon Appstore or the App Store and check for updates there.
• Installs from the Releases page tell you a new version is out. Download the new file and install it over the old one, exactly as the first time. See Installation.
• Sideloaded iPhone and Apple TV copies have to be signed again with the new file.
• Your current version is shown under Settings > About.

Reinstalling still shows my old server and profiles

That data wasn't left behind by accident, and on most platforms an uninstall does remove it. The usual culprits are an Android backup restoring your settings, a desktop uninstaller leaving your configuration folder in place, or on macOS the container under ~/Library/Containers surviving a drag to the Trash.

Where Your Data Is Stored lists the exact path for every platform and how to clear it properly.

Still stuck

1. Follow Collecting Logs. It takes two minutes and is usually the difference between a fix and a shrug.
2. Open a GitHub issue with the log, your device, the app version from Settings > About, and what you expected to happen.
3. For quick questions, the Discord is friendly.