Troubleshooting

Boot issues

Black screen, just the splash

Wrong panel overlay. Most common cause when first flashing a clone device with a recent motherboard revision.

Fix: re-flash with the Flasher and pick the exact silkscreen-printed motherboard revision in the panel dropdown.

Boot loops, never reaches ES

Three possibilities, in order of likelihood:

CPU instability at turbo (only with Enable CPU Overclock on, very rare). Power off, remove SD, edit /storage/.config/system.cfg from a PC and set enable.turbo-mode=0.
fs-resize hung on first boot. Capture cat /storage/.boot_last_hang after the eventual successful boot — that file names the script that stalled.
Wrong image variant (original on a clone or vice versa). Re-flash with the right variant.

Boot reaches ES but freezes there

Stop ES, then check what's holding things up:

sudo systemctl stop emustation
sudo journalctl -t archr-autostart -f

Or read the boot log (/var/log/boot.log — note that journald is volatile so logs from the previous boot are lost). Restart ES with sudo systemctl start emustation once you've identified the issue.

"Boot anterior travou em <script>"

The trace mechanism caught a hang on the previous boot. The named script is the culprit. Open an issue with:

The script name from /storage/.boot_last_hang
dmesg | tail -200 from the post-recovery boot
The output of cat /flash/fs-resize.log if applicable

Display

Colors look wrong / inverted

Panel BGR vs RGB swap — happens on a few clone variants where the silkscreen printed the wrong revision label. Re-flash with the next-numerically-similar revision.

Screen "tearing" in some emulators

video_threaded is on by default. For tearing-sensitive games, in RetroArch Quick Menu → Settings → Video → Output → Vertical Sync = ON.

Brightness has fewer steps than I'd like

ArchR uses 3% / step (33 distinct levels). If you need finer control, edit /storage/.config/profile.d/099-freqfunctions and adjust the brightness step.

Audio

No sound at all

amixer get 'Playback Path'    # should be SPK or HP
amixer get DAC                # should be > 0
cat /sys/class/extcon/*/state # HP detect (1 = plugged)

If Playback Path is wrong, force it: amixer set 'Playback Path' SPK.

Audio crackle in Mario 64 / 3D-heavy games

If you're seeing crackle plus unbalanced disables for vdd_logic in dmesg, you're on a pre-v8 build. Update to the latest release — the mali_kbase PM patch eliminates this.

If still happens on latest: open an issue with dmesg | grep -iE 'vdd_logic|clk_gpu|mali' and the game name.

Bluetooth audio choppy

A2DP latency is sensitive to the BT codec. Force SBC + low-quality if your device only supports basic profiles:

pactl set-sink-port bluez_sink.<MAC>.a2dp-sink "speaker-output"

In ES Bluetooth menu, the toggle "Force SBC" does the same.

Performance

Game runs slower than expected

In order:

CPU governor — should be performance during gameplay. Verify: cat /sys/devices/system/cpu/cpufreq/policy0/scaling_governor.
GPU governor — should be performance. cat /sys/class/devfreq/ff400000.gpu/governor.
CPU max freq — cat /sys/devices/system/cpu/cpufreq/policy0/scaling_max_freq. Without overclock = 1416000, with overclock = 1512000.
Background services — systemctl is-active syncthing tailscaled zerotier-one simple-http-server. Should all be inactive during a game (they're paused automatically by runemu.sh).
Thermal throttling — cat /sys/class/thermal/thermal_zone0/temp (units: m°C). Above 70 000 (70 °C) triggers passive throttle. Take a break, let it cool.

Run the bench

For repeatable diagnostics:

bash /flash/bench.sh psp 60   # tag the scenario, duration in seconds

Results in /storage/bench-results/<timestamp>-psp/ — summary.json has p99-style aggregates, psi.log has per-second pressure stalls, freq-therm.log has the freq trajectory.

Storage / ROMs

Some ROMs don't appear after copying

ES rescans only at boot. ES menu → Game Settings → Rescan ROMs → wait → ROMs appear.

"Disk full" but my SD is huge

Check that the partition was resized: df -h /storage. Should show ~95% of the SD capacity. If not, fs-resize didn't run; the marker file /storage/.please_resize_me triggers it on next boot:

sudo touch /storage/.please_resize_me
sudo reboot

Save-states gone after re-flash

They live in /storage/saves/. If you re-flashed and the partition was wiped (Flasher always wipes), they're gone. Back up next time:

scp -r root@archr.local:/storage/saves ~/r36s-saves-backup/

SSH / network

Can't connect: "connection refused"

SSH is off by default. ES → System Settings → Network → Enable SSH → ON.

"archr.local" doesn't resolve

Avahi/mDNS issue. Use the IP (visible in ES → System Information). Or:

# from a Linux/macOS box
avahi-browse -art | grep archr

WiFi connects but no internet

DNS issue. Try:

sudo systemctl restart connman
sudo connmanctl scan wifi
sudo connmanctl services

ssh root@archr.local
bash /usr/bin/start_portmaster.sh

Read the trace. The script is idempotent (re-running is safe).

How to file a useful bug report

1. Hardware           ────  R36S V21 / K36 / RX6S etc.
2. ArchR version      ────  in ES System Information, or `cat /etc/os-release`
3. Image variant      ────  original | clone
4. Panel selected     ────  silkscreen-printed motherboard revision
5. What you tried     ────  exact steps to reproduce
6. What happened      ────  observed vs expected
7. Logs:
   /var/log/boot.log
   dmesg | tail -200
   /storage/.boot_last_hang   (only exists if the previous boot hung)
   /flash/fs-resize.log       (if first-boot related)

Open at github.com/archr-linux/Arch-R/issues.

For PortMaster specifically: github.com/PortsMaster/PortMaster-GUI/issues.