Common Problems

Common Problems

Plain fixes for the things people ask about most on Samsung and LG TVs. 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 your phone, on the same Wi-Fi as the TV. If the browser can't reach it either, the address or the network is the problem, not the TV.
2. Check the port. Moonfin tries 8096 and 8920 by itself. If the server uses another port, type it after the address, like mynas:8000.
3. Is the TV on the same network as the server? Addresses like 192.168.x.x or a plain name only work at home. A TV on a guest network can't see the rest of the house.
4. Home-made (self-signed) certificate on an https address: on LG, turn on Settings > Account & Security > Connection > Allow Untrusted Certificates. On either brand, the plain http:// address works at home.
5. Old LG TV and a Let's Encrypt certificate: older webOS models don't trust modern certificates. Moonfin carries its own up-to-date certificate list for the app's own requests, so this usually works. If it still fails, Allow Untrusted Certificates is the switch to try.
6. Server version is not supported. Minimum: 10.9.0. Your Jellyfin is too old for this app. Update the server.
7. Is the server actually running? Restart it, and check its firewall allows the port.

The app says No Internet Connection

Moonfin only shows this screen when it really can't reach your server. The TV saying it's offline isn't enough. Moonfin asks the server first. So it's the same problem as above: check the server is running and the TV is on the same network, then press Retry, which asks the server again. Blocking the TV maker's own servers, with a Pi-hole for example, doesn't cause it.

Login failed

• Usernames and passwords are case sensitive, and the TV keyboard makes it easy to hit the wrong page of symbols. Check what you typed, or sign in with Quick Connect instead.
• After several wrong attempts the server locks the account for a while. An admin can unlock it.
• Quick Connect is disabled means an admin has to turn it on under the Jellyfin Dashboard > General. Codes expire after a few minutes, so ask for a new one if it sat on the screen.
• Emby Connect needs the server to be linked to your Emby Connect account on the Emby side.
• Too many attempts. Try again in... after a wrong PIN: PIN Code Protection and Kids Mode make you wait after five wrong tries, longer with each one, up to 15 minutes. Wait it out and try again.

Installing fails, or the app vanished

Samsung

• Apps2Samsung can't find the TV: the IP address you typed into the TV's Developer Mode window must be the PC running Apps2Samsung, both must be on the same network, and the TV must be fully restarted (power off, not just standby) after turning Developer Mode on.
• Developer Mode won't open: on the Apps screen press 1, 2, 3, 4, 5 on the remote in a row, without pausing.
• "Install failed" or a permission message on a TV that used to work: turn Developer Mode off, restart, turn it on again with the PC's current IP.

LG

• The app disappeared after a couple of days: Developer Mode's timer ran out and the TV removed the apps installed with it. Turn Developer Mode on again, install Moonfin again, and press Extend in the Developer Mode app now and then. The Homebrew Channel route doesn't expire.
• Dev Manager Desktop or ares-setup-device can't connect: Key Server must be on in the Developer Mode app, and the passphrase changes each time the TV restarts. Re-enter it.

Full steps for both are on Installation and Sideloading.

Video is blurry, stutters, or the server gets loud

When the TV 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.

Reason	Fix
Slow Wi-Fi to the TV	Use a network cable. A 4K file needs a steady, fast connection
A quality limit is set	Playback & SyncPlay > Video Playback Preferences > Transcoding Limits > Max Resolution should be Auto. Max Streaming Bitrate on Auto follows LG's published limits: 40 Mbps on a Full HD TV, 60 Mbps on a 4K TV (50 on webOS 3) and 100 Mbps on an 8K TV. A 4K remux above that gets transcoded, so pick a higher value if your network keeps up
Prefer Transcoding is on	Turn it off in the same screen. Leave Force Direct Play off too. It's a debug switch that skips every check, so a file the TV can't handle gets sent anyway and fails or freezes instead of being converted
The audio track is something the TV can't play	Pick another audio track before playing, or set up passthrough if you have a receiver (next section)
A 4K file on a Full HD TV	The TV can't show 4K, so Moonfin asks for 1080p and the server converts it. That's expected
Dolby Vision profile 7 on a Samsung without Dolby Vision	The server remuxes it with the Dolby Vision taken out, which leaves the HDR10 picture. A remux only repackages the file, so it's easy on the server, and it's on purpose. Nothing to fix
Dolby Vision in an MKV on an LG older than webOS 25	Those sets don't show Dolby Vision from an MKV, so the server remuxes it. Nothing to fix
HEVC inside a .ts file on a Samsung older than Tizen 6	Those sets can't direct play it. The server converts it
DVD or DVB picture subtitles	The server has to burn them in. Choose a text subtitle track instead

To see what happened: turn on logging (Settings > About > Diagnostics & Logging), play the item again, and the report names who declined direct play and why. See Collecting Logs.

No sound, or no sound on some movies

• Playing through the TV's own speakers: TVs can't play DTS or TrueHD. Go to Playback & SyncPlay > Audio Preferences and set Audio Passthrough to Auto. If a film is still silent, set Downmix to Stereo on for that TV.
• A soundbar or AV receiver over HDMI ARC or eARC: set Audio Passthrough to Auto. If the receiver supports more than Auto detects, open Passthrough Settings and allow the formats it handles. Force TrueHD / Atmos Passthrough exists for sets that misreport what they're connected to.
• On LG, TrueHD passthrough is marked experimental. If a film has no sound with it on, turn that one format off.
• Sound out of sync: the player has an audio delay control. Small offsets are normally the TV's picture processing, try the TV's game or PC picture mode.

Subtitles missing, wrong, or ugly

• Pick the track on the movie or episode page before playing, or from the player's Subtitles button.
• When subtitles load on their own is decided by Playback & SyncPlay > Subtitle Preferences > Subtitle Mode, together with the default language there.
• Size, position, colors and background are under Subtitle Customization. HDR films use the separate HDR style if it's on.
• Picture subtitles (PGS) and styled subtitles (ASS/SSA) render on the TV when the Direct play toggles under Subtitle Rendering are on. If one type looks wrong, turn its toggle off and the server takes over.
• On LG, the first styled (ASS/SSA) lines are missing when a film starts or resumes: they take a few seconds to load on a slower TV. Turn on Subtitle Preferences > Subtitle Rendering > Wait for ASS/SSA subtitles and the video waits up to 15 seconds for them.
• On LG, picture (PGS) subtitles take a long time to appear: PGS inside an MKV that direct plays is read straight from the file, so it shows from the start. Anything else, like a transcode or an MP4, waits for the server to pull the subtitle track out of the whole file first, which can take minutes on a big remux. If an MKV still waits, it's one Moonfin can't read this way, and it falls back to the server's copy.
• No suitable track? The details page can download one, if the server has the OpenSubtitles plugin.

The menus are slow or the picture stutters while browsing

Older and cheaper sets don't have much power. Under Personalization > General Style:

• Set Performance Mode to Performance.
• Turn Browsing Background Blur off and Background Backdrops off.
• Turn Focus Expansion Animation off.
• Under Personalization > Media Bar, turn off trailer previews or the whole media bar.

The picture is wrong (colors, HDR, zoom)

• Colors off in Dolby Vision or HDR: check the TV's HDMI input mode if the server is on a box, and the TV's picture mode. Most Samsung TVs can't show Dolby Vision, so Dolby Vision files play their HDR10, HDR10+ or HLG layer there by design.
• A Dolby Vision film freezes a couple of minutes in on a Samsung: update Moonfin. On a Samsung that can't decode Dolby Vision, current versions have the server remux profile 7 files with the Dolby Vision taken out, which is what stops the freeze.
• Black bars where there shouldn't be, or a cropped picture: Playback & SyncPlay > Video Playback Preferences > Player Zoom Mode.
• The time shown in the app is wrong: Personalization > General Style > Clock Offset.

Xbox

• The Device Portal refuses the install with error 0x80073cf3, saying the package depends on a framework such as Microsoft.UI.Xaml.2.8 that was not found: the five .appx files from the Dependencies folder weren't added. Run the install again, tick Allow me to select framework packages before clicking Next, and choose all five. See Installation and Sideloading.
• The same error with all five .appx files added: the console most likely already has an older copy of that framework from another sideloaded app, and the portal keeps the old copy instead of taking the newer one from the dependency list. Install the framework on its own first, with Add and Dependencies/Microsoft.UI.Xaml.2.8.appx chosen as the package (no box to tick), Next, then Start. Repeat for any other framework the error names, then install Moonfin again.
• Text and posters look a little soft on a 4K set: the console draws every app's interface at 1080p and scales it to the TV. Plex and Jellyfin look the same, and video is not affected, it plays at 4K and in HDR.
• Can't sign in to a server with a self signed https certificate: use the server's http address for now. The setting that allows untrusted certificates can't be reached before sign in.
• An HDR film looks flat and far too bright: update Moonfin. 2.10.0 marks the frames as HDR and switches the display.
• Something plays wrong through the console's player: Playback & SyncPlay > Video Playback Preferences > Decoding & Rendering > Console Video Player turns it off for the next playback, and tell us which file it was.

Home screen is empty or rows are missing

• Rows can be switched off. Check Personalization > Home Screen > Home Sections and Home Row Toggles.
• Settings only shows Exit Kids Mode: Kids Mode is on, and it keeps only My Media, Recently Added and one Continue Watching and Next Up row on Home. Exit it with its PIN.
• Some titles are missing everywhere, not just on Home: check Account & Security > Blocked Ratings. Blocking a rating also hides everything rated stronger.
• A library can be hidden under Personalization > Libraries > Library Visibility.
• Rows from Seerr, IMDb, TMDB and calendars need the Moonbase plugin enabled under Integrations.
• If a whole server's rows are gone, go to the server screen and check it's still connected.

Seerr buttons don't appear, or requests fail

• Integrations > Moonbase Plugin must say the plugin is detected and Enable Plugin must be on. If it says the server doesn't have the plugin, it has to be installed on the Jellyfin or Emby server first.
• Then sign in under Integrations > Seerr. Nothing else is entered on the TV, the Seerr address lives in the plugin's settings on the server.
• Browsing works but requests fail: recheck the Seerr URL in the plugin's configuration on the server.
• Behind a reverse proxy, the /Moonfin/ paths must be forwarded. See the plugin's Reverse Proxy and Seerr page.

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. Open Seerr's Radarr settings, 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 remote does something odd

• A red console pane appeared on the right: you pressed the Red button, which opens the debugging overlay. Press Red again to close it.
• The app closes when you press Back on the home screen: that's how Back works at the top level. Account & Security > Confirm Exit adds a yes or no first.
• Fast forward does nothing during Live TV: seeking isn't available on live channels.
• A strip of channels slides up during Live TV: pressing Up there opens the channel changer. Down or Back closes it.
• A game controller doesn't work in games: see the plugin's Retro Games page.

The app says a new version is available

Moonfin checks GitHub once a day. It can't update itself. Download the new file and install it the same way as the first time. See Updating. The notice can be turned off under Settings > About > Update Notifications.

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 report, your TV model and OS version (Settings > About > Device), the app version (Settings > About > APP INFO), and what you expected to happen.
3. For quick questions, the Discord is friendly.