Troubleshooting

Troubleshooting

Start with SYSTEM DIAGNOSTICS (Settings): it shows the OS, GPU and driver, video decoding, audio, network, Tailscale, USB and display details. Commands on this page run in the TERMINAL app (in the live session sudo needs no password). If you still need help, report a bug with a support file.

Quick table

Symptom	Try
USB stick does not boot	USB does not boot
Black screen, no launcher	The screen stays black
An update broke the box	The update broke my box
A text menu instead of the TV home screen	The classic interface
Moonlight stream is black	Moonlight stream is black
Moonlight closes right away	Check /var/log/couchliteos/moonlight.log
Stream stutters	Settings > STREAMING > STREAM CHECK; use a cable; then SMOOTHER STREAM
Gaming PC not found when pairing	It is off or asleep, Sunshine is not running, or it is on another network. Try WAKE PC, SEARCH AGAIN or ENTER ADDRESS MANUALLY.
No controller input in games (Windows PC)	Install ViGEmBus on the gaming PC
No sound on the TV	Settings > AUDIO: pick the HDMI/DisplayPort output. Check the TV's volume and input.
Bluetooth headphones lag behind the picture	Settings > AUDIO > BLUETOOTH DELAY; wired or HDMI audio is best for fast games
Microphone not heard in a Moonlight stream	Moonlight streams do not carry the microphone; Settings > AUDIO > MICROPHONE > ABOUT VOICE CHAT
A game has no cover, or the wrong one	Hold Y / Square (or F9) on it for CHANGE ARTWORK (Game Covers)
No web browser, or LO-FI RADIO says ADD A WEB BROWSER TO PLAY	Settings > APPLICATIONS > ADD A WEB BROWSER (needs the internet)
An app misbehaves after an app update	Settings > SOFTWARE UPDATE > ROLL BACK app
No network	Plug in a cable, or Settings > NETWORK > JOIN A WI-FI NETWORK. Check nmcli device and ip -4 route. IPv6 is disabled on purpose.
Wi-Fi password changed	Settings > NETWORK, choose your network again and type the new password
Picture cut off at the edges	Settings > DISPLAY > SCREEN EDGES
Text too big or small	Settings > DISPLAY > TEXT SIZE
A new display mode looks wrong	Wait 15 seconds, or press B / Esc: the old mode comes back
Saved display mode not restored	The screen, cable or port changed; set it again in Settings > DISPLAY
chiaki-ng black screen	PlayStation with chiaki-ng
Remote Desktop will not connect	Remote Desktop
Cannot get back to the home screen	Tap Guide / PS for the quick menu (outside a stream); hold SELECT+START 1.5 s (Guide / PS goes to a stream); Ctrl+Alt+H (or your keyboard Home key) (Controls)
Tailscale offline	couchliteos-tailscale-diagnostics; local streaming still works
USB/IP device refused	sudo couchliteos-usbip list; check the exact serial and the :risky rule (USB/IP)
Support file not saved	Support File and Privacy

USB does not boot

1. Check the download against SHA256SUMS, then write the ISO to the whole stick as a raw image (Rufus in DD Image mode, balenaEtcher, or dd), not as a file copy. See Install.
2. In the firmware boot menu (Dell: F12; Mac: hold Option) choose the UEFI USB entry. Try another USB port.
3. The CouchLiteOS menu needs a keyboard; it ignores controllers.
4. The launcher does not wait for the network, so an unplugged cable does not stop it from appearing.
5. Still stuck? Photograph the last message on screen and report it.

The screen stays black or the launcher never appears

Without the launcher there is no way to type commands, so the fixes are all in the boot menu (keyboard needed). On the live USB press an arrow key within three seconds of the menu appearing. An installed box hides the menu: hold Shift (BIOS) or press Esc (UEFI) while it starts; after a failed boot it shows the menu for 5 seconds by itself.

1. NVIDIA ISO: choose Start CouchLiteOS (Basic Graphics). On an installed box, press e on the GRUB entry, add couchliteos.gpu=basic to the end of the line starting with linux, and press Ctrl+X.
2. Secure Boot on: CouchLiteOS falls back to the open driver. Turn Secure Boot off in the firmware setup to use NVIDIA's driver.
3. A saved setting (such as a display mode the screen cannot show): choose Start CouchLiteOS (No Persistence) on the live USB.
4. Try another cable, port, or display.
5. Never add nomodeset: CouchLiteOS needs the graphics driver.
6. Nothing works? Photograph the screen and report the PC model and graphics card (from its label or another operating system).

If the launcher appears but looks garbled, run /usr/libexec/couchliteos-hwdetect report to see which driver was chosen and why. On the NVIDIA ISO, if Basic Graphics works and the normal entry does not, report the GPU (lspci -nn | grep -i nvidia) and the hwdetect report from the Basic Graphics start. RTX 50 cards are not supported yet.

Moonlight stream is black

If Moonlight receives and decodes frames (see moonlight.log in the support file), CouchLiteOS is showing exactly what the gaming PC sends: the PC is capturing a black picture. Check the gaming PC:

• No monitor attached. Sunshine's log (Web UI > Troubleshooting > Logs) shows Currently available display devices: [] or a 1024x768 desktop. Plug in an HDMI/DisplayPort dummy plug, keep a monitor on, or install a virtual display driver, then set Configuration > Audio/Video > Output Name to that display.
• A Remote Desktop session holds the screen. Sign out of RDP, or send the session back to the console (Command Prompt as administrator): for /f "skip=1 tokens=3" %s in ('query user %USERNAME%') do tscon.exe %s /dest:console
• Lock screen or UAC prompts are black: run Sunshine as a service (the default Windows install).
• Protected video (streaming services in a browser on the PC) is always black.
• Try HDR off on the PC, and the other capture method in Sunshine's Configuration > Advanced.

The update broke my box

Every update saves the system it replaces (unless SAVE BEFORE UPDATE is off).

• The box still starts: Settings > SOFTWARE UPDATE > RESTORE PREVIOUS VERSION. The box restarts and puts the saved version back, with the settings and pairings it had then.
• The box no longer starts: show the boot menu (hold Shift on BIOS PCs, or press Esc on UEFI PCs, while the box starts) and choose CouchLiteOS: restore previous version.

Only one version is kept. Details: Updating.

The classic interface

A text menu instead of the TV home screen means one of two things:

• INTERFACE is set to CLASSIC. Choose Settings > APPEARANCE > INTERFACE > TV to go back.
• The TV interface could not start on this PC, so the box started the classic interface by itself. Everything still works there: streaming, Settings, updates. If it keeps happening, report a bug with a support file.

On PCs without 3D graphics the TV interface still runs, but the wave stands still and animations are shorter.

No sound on the TV

1. Settings > AUDIO lists every output, including ones the sound card can only use after switching mode. Pick the HDMI/DisplayPort one; the choice is kept.
2. Check the TV's own volume, and that it is on the right input.
3. Bluetooth headphones or a speaker take the sound while they are connected; it moves back when they disconnect.
4. wpctl status and aplay -l in TERMINAL show what the system sees.

iMac Late 2013

• Black screen: choose Start CouchLiteOS (No Persistence). Do not add nomodeset. An iMac14,1 (check About This Mac or the label) has Intel graphics and is a different machine.
• No Wi-Fi: run lsmod | grep '^wl '. On an installed box, keep linux-headers-amd64, dkms and broadcom-sta-dkms installed so the driver is rebuilt after kernel updates.

More in iMac Late 2013.

Never do this

• Do not port-forward Sunshine or USB/IP to the internet.
• Do not open Tailscale's UDP port 41641 on your router blindly; run tailscale netcheck and tailscale ping first.