Common Problems

Common Problems

Plain fixes for the things people ask about most on Roku. Try the steps in order. The last section says what to send if none of them help.

Can't reach the server

1. Open the address in a web browser on your phone, on the same Wi-Fi as the Roku. If the browser can't reach it either, the address or the network is the problem, not the Roku.
2. Check the port. The standard is 8096. If your server uses another, type it after the address, like mynas:8000.
3. Same network? A Roku on a guest network can't see the rest of the house. Addresses like 192.168.x.x only work at home. Away from home you need an address the server owner set up for outside access.
4. https with a home-made certificate is refused by the Roku. Use the plain http:// address at home, or ask the server owner for a proper certificate.
5. The Roku's DNS: if the server has a name rather than an IP and the Roku can't resolve it, try the IP address instead.
6. Is the server actually running? Restart it, and check its firewall allows the port.

Sign-in trouble

• Passwords are case sensitive, and the on-screen keyboard makes it easy to hit the wrong page of symbols. Use Quick Connect instead, it needs no typing.
• The Quick Connect tab is missing: an admin has to turn it on under the Jellyfin Dashboard > General. Codes expire after a few minutes, back out and in for a new one. Emby has no Quick Connect, so Emby servers show an Emby Connect button instead.
• Emby Connect doesn't list your server: the server has to be linked to that Emby account in the Emby dashboard. Or skip Emby Connect, choose Enter Server URL, and sign in with a local account on the server.
• After several wrong attempts the server locks the account for a while. An admin can unlock it.
• Signed in but everything is empty: the account has no library access. That's set per user in the server dashboard.

The channel won't install or won't open

• Channel Store: the Roku must be on Roku OS 9.1 or newer (Settings > System > About). Older devices don't see Moonfin in the store.
• Added from the website but not on the Roku: restart it from Settings > System > Power > System restart, or check the Roku is signed in to the same Roku account.
• Sideload upload fails: the Developer Mode page needs the username rokudev and the password you made when enabling it. Upload the .zip as is, don't unzip it. If the page says another dev channel is installed, click Delete first.
• Sideloaded Moonfin vanished: another sideloaded channel replaced it. Only one fits at a time. Install Moonfin again.

Video stalls, looks blurry, or the server gets loud

When the Roku can't play a file as it is, the server converts it on the fly. That's called transcoding. It makes the server work hard, can look softer, and stalls if the server can't keep up.

Reason	Fix
Wi-Fi to the Roku is too slow	Use a network cable (Roku Ultra and Roku TVs have a port), or move the router. A 4K file needs a steady, fast connection
A bitrate limit is set too low	Settings > Playback > Video Playback Preferences > Bitrate Limit
The TV is 1080p but the file is 4K	Set Maximum Resolution to match the TV so the server sends a smaller stream
Force Transcoding or a Compatibility mode is on	Turn them off in the same screen unless you set them on purpose
The audio track is one the Roku can't decode	Pick another audio track before playing, or check the Roku's own Settings > Audio (next section)
Picture subtitles (PGS)	Try Burn in subtitle when transcoding or Text Subtitles Only under Subtitle Preferences, or pick a text subtitle track
Dolby Vision profile the Roku doesn't support	Moonfin falls back to HDR or SDR on its own. If colours look wrong, that's the fallback and the file needs a transcode

To see what happened: turn on Settings > Moonfin Settings > Diagnostics > Diagnostic Logging, play the item again, then read View Logs.

No sound, or no surround sound

Roku decides what audio formats leave the HDMI port, not Moonfin.

• On the Roku go to Settings > Audio and set the HDMI (or S/PDIF) mode. Auto detect is right for most setups. Pick Dolby D or DTS by hand only when a receiver isn't detected properly.
• Playing through the TV's own speakers: the Roku converts surround tracks to stereo. If a film is silent, try Settings > Playback > Audio Preferences > Maximum Audio Channels set to 2.
• A receiver that supports more than Auto detect finds: set the Roku's audio mode by hand, then in Moonfin check Preferred Audio Codec under Audio Preferences.
• Sound out of sync: usually the TV's picture processing. Try the TV's game or PC picture mode.

Subtitles missing, wrong, or out of step

• Pick the track on the movie page before playing, or from the player controls. Off means none is selected.
• When subtitles load on their own: Settings > Playback > Subtitle Preferences > Subtitle Mode, together with Default Subtitle Language.
• Out of step: open Adjust Subtitle Timing from the player controls and nudge the offset.
• Styled subtitles (ASS) and picture subtitles (PGS) play directly when their Direct Play toggles are on under Subtitle Preferences. If one type looks wrong, turn its toggle off and the server takes over.

The home screen is empty or rows are missing

• Rows can be switched off. Settings > Moonfin Settings > Home Screen > Home Row Toggles and Home Row Sections.
• Rows from Seerr, IMDb, TMDB and calendars need the Moonbase plugin, enabled under Settings > Moonfin Plugin.
• A library hidden on the server for your user won't show anywhere.
• If a whole server's rows are gone, check it's still reachable from the server screen.

Settings don't follow me to another device

• Both devices need Settings > Moonfin Plugin > Enable Plugin on, the plugin installed on the server, and the same Jellyfin or Emby user signed in.
• Some settings are meant to differ per device type. The Moonbase Settings Sync page explains the layering.
• Settings Sync under Moonfin Plugin can push this Roku's settings up or pull the server's down by hand.

Seerr doesn't show up, or requests fail

• Settings > Moonfin Plugin > Enable Plugin must be on and the plugin must report as found.
• Then Settings > Moonfin Plugin > Seerr > Enable Seerr and sign in under Account & Sign In.
• Sign-in fails: the Seerr URL on the server is wrong, or your Jellyfin or Emby user hasn't been imported into Seerr yet. Both are fixed on the server side.
• Requests submit but never appear: your Seerr user lacks request permission. That's granted inside Seerr.

The remote does something odd

• The app closes when you press Back on the home screen: that's how Back works at the top level. Use the navigation bar to move around instead.
• Rewind or Fast Forward seem stuck at high speed: press the opposite direction to slow down, or OK to land.
• Nothing happens on Left or Right in the player: the controls are up. Press Back to hide them, then Left and Right skip again.

Still stuck

1. Turn on Settings > Moonfin Settings > Diagnostics > Diagnostic Logging, make the problem happen again, and open View Logs. Take a photo of the screen or note the lines around the failure.
2. Open a GitHub issue with your Roku model and OS version (Settings > System > About), the Moonfin version (Settings > Moonfin Settings), your Jellyfin version, and what you expected to happen.
3. For quick questions, the Discord is friendly.