Troubleshooting

Solutions to common problems with HelixScreen.

Quick Debugging Guide
Startup Issues
Connection Issues
Display Issues
Touch Input Issues
Print Issues
AMS/Multi-Material Issues
Spoolman Issues
Calibration Issues
Performance Issues
Configuration Issues
Flashforge Adventurer 5M Issues
Gathering Diagnostic Information
- Enabling Debug Logging
- Collecting Logs
Getting Help

Quick Debugging Guide

Before troubleshooting anything, increase log verbosity:

# MainsailOS - edit service temporarily
sudo systemctl edit --force helixscreen
# Add these lines (use your actual install path):
[Service]
ExecStart=
ExecStart=~/helixscreen/bin/helix-launcher.sh -vv

# Then restart
sudo systemctl daemon-reload
sudo systemctl restart helixscreen

# Watch logs
sudo journalctl -u helixscreen -f

Verbosity levels:

No flag: WARN only (production default)
-v: INFO - connection events, panel changes
-vv: DEBUG - detailed state changes, API calls
-vvv: TRACE - everything including LVGL internals

Remember to remove -vv after debugging - verbose logging impacts performance.

Startup Issues

HelixScreen crashes immediately (segfault)

Symptoms:

Service starts then immediately exits
“Segmentation fault” in logs
Black screen, no UI appears

Common causes:

Missing or corrupt assets (use your actual install path)

# Check assets exist (Pi: ~/helixscreen or /opt/helixscreen)
ls -la ~/helixscreen/assets/
ls -la ~/helixscreen/assets/fonts/
ls -la ~/helixscreen/xml/

Wrong display backend for your hardware

# Check what display devices exist
ls -la /dev/fb*      # Framebuffer devices
ls -la /dev/dri/*    # DRM devices

# Pi 4 typically uses /dev/dri/card1
# Pi 5 may use /dev/dri/card1 or card2
# Flashforge Adventurer 5M (AD5M) uses framebuffer /dev/fb0

Permission issues

# Check user is in required groups
groups
# Should include: video, input, render

”No display device found”

Symptoms:

Log shows “No suitable DRM device found” or similar
Service keeps restarting

Solutions:

Specify the DRM device explicitly:

// ~/helixscreen/config/settings.json (or /opt/helixscreen/config/)
{
  "display": {
    "drm_device": "/dev/dri/card1"
  }
}

For Pi 5, try different cards:

card0 = v3d (3D acceleration only, won’t work)
card1 = DSI touchscreen
card2 = HDMI via vc4

Logs are empty or not appearing

Symptoms:

journalctl -u helixscreen shows nothing useful
Log file doesn’t exist

Causes:

Log destination misconfigured
Service not actually running
Crash before logging initializes

Solutions:

Check service status first:

sudo systemctl status helixscreen

Force console logging for debugging:

# Run manually to see all output (use your actual install path)
sudo ~/helixscreen/bin/helix-screen -vvv

Check log destination in config:

{
  "log_dest": "auto",
  "log_level": "info"
}

Valid log_dest values: auto, journal, syslog, file, console

Connection Issues

”Cannot connect to Moonraker”

Symptoms:

Red connection indicator on home screen
“Disconnected” status
Cannot control printer

Causes:

Wrong IP address or port
Moonraker not running
Firewall blocking connection
Network issues

Solutions:

Check Moonraker is running:

sudo systemctl status moonraker

If stopped: sudo systemctl start moonraker

Verify the IP address:

# On the Pi running Klipper
hostname -I

Update config with correct IP.

Test connection manually:

curl http://localhost:7125/printer/info

Should return JSON with printer info.

Check firewall:

sudo ufw status
# If active, allow Moonraker:
sudo ufw allow 7125/tcp

“Connection lost” during print

Symptoms:

Disconnect toast appears
UI shows “Disconnected”
Print continues (Klipper handles it)

Causes:

Network instability (WiFi)
Moonraker timeout
Power management issues

Solutions:

Use Ethernet if possible - wired connections are more reliable.

Check WiFi signal strength:

iwconfig wlan0 | grep -i signal

Disable WiFi power management:

sudo iw wlan0 set power_save off

To make permanent, add to /etc/rc.local:

iw wlan0 set power_save off

Increase Moonraker timeouts:

{
  "printer": {
    "moonraker_connection_timeout_ms": 15000,
    "moonraker_request_timeout_ms": 60000
  }
}

Note: Values are in milliseconds (15000ms = 15 seconds).

WiFi won’t connect

Symptoms:

WiFi setup in wizard fails
Network not found
Authentication failures

Solutions:

Verify WiFi is working at OS level:

nmcli device wifi list

Check NetworkManager is running:

sudo systemctl status NetworkManager

Manual WiFi connection:

sudo nmcli device wifi connect "YourSSID" password "YourPassword"

For hidden networks:

sudo nmcli device wifi connect "HiddenSSID" password "Password" hidden yes

Note: Older guides may reference wpa_supplicant directly, but MainsailOS and most modern systems use NetworkManager. Use nmcli commands instead.

WiFi permission denied

Symptoms:

WiFi scan shows no networks (but WiFi works from command line)
“Permission denied” error when connecting
WiFi worked before an update but stopped working

Cause: HelixScreen needs permission (via polkit rules) to manage WiFi through NetworkManager. These rules are installed automatically, but can be missing if:

HelixScreen was installed before NetworkManager was set up
A self-update couldn’t install permission rules (runs with restricted privileges)
The polkit rules file was deleted or corrupted

Solutions:

Re-run the installer (recommended — installs correct polkit rules):

curl -fsSL https://install.helixscreen.org | bash

Verify polkit rules are installed:

# Check for HelixScreen polkit rules (one of these should exist)
ls -la /etc/polkit-1/rules.d/50-helixscreen-network.rules
ls -la /etc/polkit-1/localauthority/50-local.d/helixscreen-network.pkla

Check NetworkManager permissions:

nmcli general permissions

If most entries show “no” instead of “yes”, polkit rules are missing.

Manual fix (if re-running installer isn’t possible):

Create /etc/NetworkManager/conf.d/any-user.conf:

[main]
auth-polkit=false

Then restart NetworkManager:

sudo systemctl restart NetworkManager
sudo systemctl restart helixscreen

Note: The manual fix disables permission checks for all users. The installer method is preferred as it only grants access to the HelixScreen service user.

SSL/TLS certificate errors

Symptoms:

Connection fails with certificate errors
Works with HTTP but not HTTPS

Cause: System time is wrong, making SSL certificates appear invalid.

Solution:

# Check current time
date

# Sync time manually
sudo timedatectl set-ntp true

# Or force sync
sudo systemctl restart systemd-timesyncd

Display Issues

Black screen on startup

Symptoms:

Display stays black
Service shows running but no output

Causes:

Wrong display driver
Permission issues
Display not detected

Solutions:

Check service is running:

sudo systemctl status helixscreen
sudo journalctl -u helixscreen -n 50

Identify your display hardware:

# Framebuffer devices (older displays, Flashforge AD5M)
ls -la /dev/fb*

# DRM devices (Pi 4/5, modern displays)
ls -la /dev/dri/*

Check display permissions:

# User needs video group access
groups
# Should include 'video'
sudo usermod -aG video $USER
# Log out and back in for group change to take effect

For DRM displays, specify device:

{
  "display": {
    "drm_device": "/dev/dri/card1"
  }
}

Wrong screen size or resolution

Symptoms:

UI too small or too large
Partial screen visible
Stretched or squished display

Solutions:

HelixScreen auto-detects resolution from DRM and framebuffer backends. If auto-detection picks the wrong resolution, override it with the -s flag:

# In helixscreen.service ExecStart, add -s with a named size or WxH:
ExecStart=/opt/helixscreen/bin/helix-launcher.sh -s large
# or: -s 1024x600
# Named sizes: micro, tiny, small, medium, large, xlarge

Then reload:

sudo systemctl daemon-reload
sudo systemctl restart helixscreen

Resolution stuck at the wrong size, or `-s` has no effect

Symptoms:

HelixScreen shows a “Cannot set HelixScreen to selected resolution” message on startup
Display is locked at 800x480 (or similar) even though you passed -s large or -s 1024x600
System journal contains [DRM Backend] or [fbdev Backend] warnings about the requested size

Cause: HelixScreen can only use resolutions the kernel exposes to it. If the kernel display driver is misconfigured, or if a fallback driver like simpledrm is active, the display is locked to whatever the bootloader programmed at power-on — HelixScreen cannot override this at runtime.

Fix on Raspberry Pi / RatOS:

Open the boot config:
Terminal window
```
sudo nano /boot/firmware/config.txt
```
Make sure this line is present and not commented out:
```
dtoverlay=vc4-kms-v3d
```
If you are using a specific HDMI mode (e.g., 1024x600), add the appropriate hdmi_cvt / hdmi_group / hdmi_mode lines per the Raspberry Pi HDMI documentation.
Reboot.
After reboot, verify the real DRM driver is now active:
Terminal window
```
ls /sys/class/drm/
```
You should see something like card0-HDMI-A-1. If you still see only card0 and dmesg | grep -i drm mentions simpledrm, the vc4 overlay did not load — double-check /boot/firmware/config.txt for typos and any conflicting dtoverlay lines.

Check what modes the kernel knows about:

cat /sys/class/drm/card0-HDMI-A-1/modes

This lists the resolutions the DRM driver will accept for the -s flag.

Display upside down or rotated

Symptoms:

Content displayed at wrong angle
Touch offset from visual

Automatic detection:

HelixScreen automatically detects display orientation on first boot using the kernel’s panel orientation setting. If your display is physically mounted upside down and the kernel knows about it (via panel_orientation=upside_down in the kernel command line), HelixScreen detects this and applies the correct rotation automatically — both the splash screen and the main UI will appear right-side up.

On framebuffer displays only (e.g., AD5M, Allwinner-based devices — not Raspberry Pi), an interactive rotation wizard runs on first boot: it cycles through 0°, 90°, 180°, and 270° — tap the screen when the text appears right-side up, then tap again to confirm. This wizard is not available on Raspberry Pi or other DRM-based displays — use the kernel panel_orientation parameter or manual config instead.

The detected rotation is saved to the config file and applied on all subsequent boots.

Setting panel orientation in the kernel (Raspberry Pi):

Edit /boot/firmware/cmdline.txt and add a video= parameter for your display connector:

video=DSI-1:panel_orientation=upside_down

Valid orientations: normal, upside_down, left_side_up, right_side_up. HelixScreen reads this on startup and applies the corresponding rotation.

Manual rotation:

Edit your config file (typically ~/helixscreen/config/settings.json or /opt/helixscreen/config/settings.json):

{
  "display": {
    "rotate": 180
  }
}

Valid values: 0, 90, 180, 270. Restart HelixScreen after changing this value. Touch coordinates are automatically adjusted to match — no separate touch configuration is needed.

How rotation works under the hood:

When you set a rotation value, HelixScreen checks whether your display hardware supports rotating the image directly (hardware rotation). Most embedded displays — including DSI screens on Raspberry Pi — do not support hardware rotation for 180°.

When hardware rotation is not available, HelixScreen automatically switches from the GPU-accelerated DRM backend to the framebuffer (fbdev) backend, which handles software rotation flicker-free. This happens transparently — you don’t need to configure anything. You’ll see this in the logs:

DRM lacks hardware rotation for 180°, falling back to fbdev (flicker-free software rotation)

The fbdev backend with software rotation works well for normal UI usage. If you notice any issues, you can also force the fbdev backend manually:

sudo systemctl edit helixscreen

Add:

[Service]
Environment="HELIX_DISPLAY_BACKEND=fbdev"

Then restart: sudo systemctl restart helixscreen

To re-run automatic detection:

Remove the rotate and rotation_probed keys from your config file’s display section, then restart HelixScreen:

{
  "display": {
    // remove "rotate" and "rotation_probed" from here
  }
}

Note: Old configs may have "display_rotate": 180 at the root level. This is automatically migrated to the new format on startup.

Colors are wrong (red and blue swapped)

Symptoms:

Red images appear blue and blue images appear red
Green colors display correctly
UI elements with red/blue tints look “off”

Cause: Your display’s framebuffer uses BGR pixel order instead of RGB, but the kernel driver reports the wrong format. This is common on some Allwinner SoCs (H616, R818, etc.) with RGB parallel (40-pin) display interfaces.

HelixScreen auto-detects BGR layout from the kernel’s fb_var_screeninfo, but some display drivers report incorrect pixel offsets. You can verify with:

fbset -i -fb /dev/fb0

Look at the rgba line. If it shows 8/16,8/8,8/0,0/24 (red at offset 16), the kernel claims RGB. If your colors are swapped despite this, the kernel is wrong and you need a manual override.

Solution:

Add this line to your helixscreen.env file (typically ~/helixscreen/config/helixscreen.env):

HELIX_COLOR_SWAP_RB=1

Then restart HelixScreen:

sudo systemctl restart helixscreen

To disable the swap (if auto-detection is wrong in the other direction), use HELIX_COLOR_SWAP_RB=0.

Verifying the fix: After restart, flags on the language selection screen should show correct colors (e.g., the French flag should be blue-white-red, not red-white-blue).

5GHz WiFi networks not showing

Symptoms:

Only 2.4GHz WiFi networks appear in the network list
5GHz networks visible in KlipperScreen or other tools but not in HelixScreen
WiFi adapter supports 5GHz (e.g., AP6256) but only 2.4GHz networks shown

Cause: HelixScreen displays all networks returned by the WiFi subsystem (wpa_supplicant or NetworkManager). If 5GHz networks are missing, the issue is typically in the underlying WiFi configuration rather than HelixScreen itself.

Solutions:

Check if your WiFi adapter sees 5GHz networks at the OS level:

# For NetworkManager systems:
nmcli device wifi list

# For wpa_supplicant systems:
sudo wpa_cli scan
sudo wpa_cli scan_results

If 5GHz networks don’t appear here either, the issue is in the WiFi driver or configuration.

Verify 5GHz support is detected:

iw phy phy0 info | grep -A 20 "Frequencies"

Look for frequencies above 5000 MHz (e.g., 5180, 5240).

Check wpa_supplicant configuration: If your wpa_supplicant.conf has a freq_list= parameter that only lists 2.4GHz frequencies, 5GHz networks won’t be scanned. Remove the freq_list line or add 5GHz frequencies.

Check country code is set: 5GHz channels require a regulatory domain. Without it, the kernel may block 5GHz scanning:

sudo iw reg get

If it shows “country 00”, set your country code:

sudo iw reg set US   # Replace US with your country code

To make permanent, add country=US to /etc/wpa_supplicant/wpa_supplicant.conf or set wifi.powersave = 2 in NetworkManager.

After changing WiFi hardware (e.g., swapping from AP6212 to AP6256), a reboot is recommended to ensure the correct driver and firmware are loaded.

Touch Input Issues

Touch not responding

Symptoms:

Display works but touch doesn’t
No response to taps

Causes:

Touch device not detected
Wrong input device
Permission issues

Solutions:

Check touch device exists:

ls /dev/input/event*
cat /proc/bus/input/devices | grep -A5 -i touch

Test touch input:

# Install evtest if needed: sudo apt install evtest
sudo evtest /dev/input/event0
# Tap screen and watch for events

Specify touch device in config:

{
  "input": {
    "touch_device": "/dev/input/event1"
  }
}

Check permissions:

ls -la /dev/input/event*
# User needs input group
sudo usermod -aG input $USER
# Log out and back in

Touch Feel — Which Setting Do I Tune?

Three separate settings control the feel of taps vs. scrolls. Match the symptom to the right knob before changing anything — they have different effects and tuning the wrong one makes things worse.

Symptom	What’s happening	Setting to change	Direction
Stationary taps register as swipes/scrolls	Touch controller drifts a few pixels while finger is still, crossing the scroll threshold	`jitter_threshold`	Raise (e.g., 15–25)
You scroll a list and a button in it fires mid-gesture	Finger released before moving far enough to commit to scroll, so the press becomes a click	`scroll_limit`	Lower (e.g., 5)
You scroll, lift your finger, and a button fires right as you lift	Touch controller reports release→re-press on lift-off	`scroll_guard`	Set to `true`
Lists feel sluggish — long coast after a flick	Scroll momentum decays too slowly	`scroll_throw`	Raise (e.g., 35)
Short flicks never travel far enough — list barely moves	Momentum decays too fast	`scroll_throw`	Lower (e.g., 15)

All four live under input in /opt/helixscreen/config/settings.json — see CONFIGURATION.md § Input Configuration for full reference.

FlashForge AD5M and AD5X presets ship with scroll_guard: true out of the box. Other platforms default to false.

Taps Register as Swipes

Symptoms:

Tapping buttons doesn’t work — the screen scrolls instead
Most or all taps are interpreted as swipe/scroll gestures
Buttons only work when tapped very quickly and precisely

Cause: Noisy touch controller (common with Goodix GT9xx and similar capacitive controllers) reports jittery coordinates even when the finger is stationary. The small coordinate changes exceed LVGL’s scroll detection threshold.

Solution: HelixScreen includes a jitter filter (enabled by default, 5 px dead zone) that suppresses this noise. If taps still register as swipes on your panel, raise the threshold:

{
  "input": {
    "jitter_threshold": 25
  }
}

Or test temporarily with an environment variable:

HELIX_TOUCH_JITTER=25 helix-screen

Set to 0 to disable the filter if it interferes with intentional short-travel gestures.

Unintended Clicks While Scrolling

Symptoms:

You drag a list to scroll and a button in the middle of it fires instead
The list jumps a little, but the click on whatever was under your finger still goes through
Happens with short or slow swipes more than long, fast flicks

Cause: LVGL treats the first few pixels of finger movement as a “press” on the widget under your finger. Only after you’ve moved past scroll_limit pixels does it cancel the press and commit to a scroll. If you release before reaching that threshold, the press becomes a click.

Solution: Lower scroll_limit so scrolling engages sooner.

{
  "input": {
    "scroll_limit": 5
  }
}

Default is 10; the UI accepts values from 1 to 20. Going too low will make intentional taps feel twitchy — any slight finger wobble will start a scroll — so settle on the lowest value that feels correct, not the smallest possible.

Note that this is a separate problem from the phantom click after a scroll (see below) and from taps being misread as swipes (see above).

Accidental Button Presses After Scrolling

Symptoms:

After scrolling a list, a button press fires when you lift your finger
Unwanted actions triggered at the end of a scroll gesture

Cause: Some capacitive touch controllers generate a phantom “clicked” event when the finger is released after scrolling. Common on FlashForge AD5M/AD5X displays.

Solution: Enable the scroll guard, which ignores taps for 80 ms after a scroll ends:

{
  "input": {
    "scroll_guard": true
  }
}

This is enabled by default on AD5M and AD5X via their hardware presets. If you see this on other hardware, enable it manually (or test with HELIX_SCROLL_GUARD=1 helix-screen).

Still getting phantom clicks with the guard enabled? The 80 ms cooldown works for most capacitive controllers but some need longer. Raise scroll_guard_cooldown_ms (range 20–500):

{
  "input": {
    "scroll_guard": true,
    "scroll_guard_cooldown_ms": 150
  }
}

Or test temporarily with HELIX_SCROLL_GUARD_COOLDOWN_MS=150 helix-screen. Try 120, 150, then 200; stop at the smallest value that eliminates the phantom tap, since going higher will start swallowing legitimate taps that closely follow a scroll.

Touch Input is Inaccurate

If taps are landing in the wrong place on screen:

Visualize touch points: To see exactly where the system registers your taps, enable debug touch visualization:
Terminal window
```
helix-screen --debug-touches
```
This draws a ripple effect at each touch point, making it easy to see if touches are offset.
Recalibrate: Go to Settings > System > Touch Calibration
If the option isn’t visible: Your screen may not normally need calibration. SSH in and run:
Terminal window
```
helix-screen --calibrate-touch
```
If the screen is too broken to navigate: SSH in and use any of these methods:
- Run helix-screen --calibrate-touch
- Set the environment variable: HELIX_TOUCH_CALIBRATE=1 in your helixscreen.env and restart
- Edit your config file: set "force_calibration": true in the input section and restart HelixScreen

See the full Touch Calibration Guide for details.

Touch is offset from visual elements

Symptoms:

Touch registers in wrong location
Have to tap above/below intended target
Touch accuracy varies across the screen

Causes:

Rotation mismatch between display and touch
Uncalibrated touch screen

Solutions:

1. Ensure rotation is set correctly:

The display.rotate setting affects both display AND touch automatically. Make sure it matches your physical display orientation:

{
  "display": {
    "rotate": 180
  }
}

Restart HelixScreen after changing. Touch coordinates rotate automatically to match — you should not need any separate touch axis configuration.

2. Run touch calibration:

Go to Settings (gear icon in sidebar)
Tap Touch Calibration
Tap the crosshairs that appear accurately
Calibration saves automatically

Note: Touch Calibration option only appears on actual touchscreen hardware, not in desktop/SDL mode.

3. Visualize touch points to diagnose:

Enable --debug-touches to see exactly where touches register, then compare with where you’re tapping:

helix-screen --debug-touches

Or set HELIX_DEBUG_TOUCH=1 in your environment for persistent debugging.

4. If calibration doesn’t help:

Try different rotate values (0, 90, 180, 270) until touch aligns with visuals. Or remove the rotation config entirely and restart to re-trigger automatic detection (see “Display upside down or rotated” above).

Calibration doesn’t help — touches still wildly off

Symptoms:

Calibration wizard completes but touches still land far from where you tap
Accuracy varies wildly across different screen regions
Recalibrating multiple times doesn’t improve things

Cause: Some touchscreen controllers report X/Y axes that don’t match the display orientation. The calibration math tries to compensate but produces a numerically unstable matrix — it technically “works” at the calibration points but falls apart everywhere else.

This is common on devices where the touch controller is mounted at a different orientation than the display panel (e.g., some Sonic Pad configurations).

Solutions:

1. Update to the latest version (recommended):

HelixScreen v0.9+ automatically detects swapped touch axes during calibration and corrects them. Update and recalibrate:

# Update HelixScreen, then recalibrate:
# Settings > System > Recalibrate Touch

2. Manual workaround (older versions):

Set the axis swap environment variable, then recalibrate:

# Add to your helixscreen.env:
HELIX_TOUCH_SWAP_AXES=1

Then restart HelixScreen and run the calibration wizard again. The swap is applied before calibration, so the resulting matrix will be clean and stable.

Print Issues

Files not appearing

Symptoms:

Print Select shows empty
“No files found”
Known files missing

Causes:

Moonraker file access issue
Wrong file path
USB not mounted

Solutions:

Check Moonraker file access:

curl http://localhost:7125/server/files/list

Verify gcodes directory:

ls -la ~/printer_data/gcodes/

For USB drives, check mount:

mount | grep media
ls /media/usb/

Print won’t start

Symptoms:

Tap Start but nothing happens
Error message about prerequisites

Causes:

Klipper not ready
Temperature safety checks
Homing required

Solutions:

Check Klipper state:

curl http://localhost:7125/printer/info | jq '.result.state'
# Should be "ready"

If “error” state, check Klipper logs:

tail -50 ~/printer_data/logs/klippy.log

Restart Klipper:

sudo systemctl restart klipper

Can’t pause or cancel print

Symptoms:

Buttons don’t respond
Print continues despite tapping Cancel

Causes:

Connection issue during print
Klipper busy processing

Solutions:

For emergency, use the E-Stop button - it appears in the header of most panels while a print is active, as well as on the home screen.

Check connection status - if disconnected, wait for reconnection.

Via terminal:

curl -X POST http://localhost:7125/printer/print/cancel

AMS/Multi-Material Issues

AMS slots not detected

Symptoms:

AMS panel shows no slots
“No AMS detected” message

Causes:

Backend not configured in Klipper
Wrong backend type detected
Backend not initialized

Solutions:

Verify backend is running:

# For Happy Hare - check if mmu object exists
curl -s http://localhost:7125/printer/objects/list | grep -i mmu

# For AFC-Klipper - check if AFC object exists
curl -s http://localhost:7125/printer/objects/list | grep -i afc

Check Klipper logs:

grep -i "mmu\|afc\|ams" ~/printer_data/logs/klippy.log | tail -20

Restart services:

sudo systemctl restart klipper
sudo systemctl restart moonraker
sudo systemctl restart helixscreen

Load/Unload fails

Symptoms:

Load command sent but no filament movement
Error messages in notification history

Solutions:

Check filament path: Ensure no physical obstructions and buffer tubes are connected.

Verify homing: Run home operation first - many load/unload macros require homing.

Check temperatures: Some backends require extruder at temperature before operations.

Spoolman Issues

Spoolman not showing

Symptoms:

No Spoolman option in AMS panel
Spool picker not available

Causes:

Spoolman not configured in Moonraker
Spoolman service not running
Connection timeout

Solutions:

Check Spoolman configuration in moonraker.conf:

[spoolman]
server: http://localhost:7912

Verify Spoolman is running:

curl http://localhost:7912/api/v1/health

Restart services:

sudo systemctl restart spoolman
sudo systemctl restart moonraker

Spool data not syncing

Solutions:

Force refresh: Navigate away from and back to the AMS panel to trigger refresh.

Check Moonraker logs:

sudo journalctl -u moonraker | grep -i spoolman

Only some spools showing in Spoolman lists

Symptoms:

Spool picker or Spoolman panel only shows a subset of your spools
Missing spools that exist in Spoolman

Cause: HelixScreen currently fetches up to 1,000 spools from Spoolman in a single request. If you have more than 1,000 spools, the rest will not appear.

Workaround: Archive or delete unused spools in Spoolman to stay under 1,000 active spools. A future release will add continuous scroll pagination to handle larger collections.

Calibration Issues

Input Shaper measurement fails

Symptoms:

Measurement starts but errors out
“ADXL not found” error

Causes:

Accelerometer not connected
SPI/I2C configuration issue
Klipper input_shaper section missing

Solutions:

Verify ADXL connection via Klipper console:

# In Mainsail/Fluidd console, or via:
curl -X POST http://localhost:7125/printer/gcode/script \
  -d '{"script": "ACCELEROMETER_QUERY"}'

Should return acceleration values, not an error.

Check Klipper config for [adxl345] or [lis2dw12] section.

Re-run calibration after fixing hardware issues.

Screws tilt shows wrong adjustments

Symptoms:

Adjustment values seem incorrect
Bed gets worse after adjustments

Solutions:

Verify screw positions in printer.cfg:

[screws_tilt_adjust]
screw1: 30,30       # Front-left
screw1_name: front left

Check probe accuracy:

# In Klipper console:
PROBE_ACCURACY

Standard deviation should be < 0.01mm.

Performance Issues

UI feels slow or laggy

Symptoms:

Delayed response to touches
Choppy scrolling
Slow panel transitions

Diagnosis:

# Check CPU and memory
top -b -n 1 | head -20

# Check if swapping (very slow on SD card)
free -h

# Check HelixScreen memory usage
ps aux | grep helix-screen

Common causes and fixes:

Cause	Fix
Debug mode in production	Remove `-vv`/`-vvv` from service, don’t use `--test`
Animations on slow hardware	Settings → Display → disable Animations
Too many G-code files	Large directories with thumbnails use more RAM
Other processes hogging CPU	Check `top` for culprits
Swapping to SD card	Reduce memory usage or add swap to USB
Hardware issues	Settings → Hardware Health - check for problems

To disable verbose logging:

Edit the service override:

sudo systemctl edit --force helixscreen
# Remove any -vv or -vvv flags
sudo systemctl daemon-reload
sudo systemctl restart helixscreen

High memory usage

Symptoms:

Out of memory errors
System becomes unresponsive
Crashes during complex operations

Solutions:

Check memory usage:

free -h

Reduce Moonraker cache in moonraker.conf:

[file_manager]
queue_gcode_uploads: False

Limit print history:

[history]
max_job_count: 100

Configuration Issues

First-run wizard keeps appearing

Symptoms:

Wizard shows on every boot
Settings not saved

Causes:

Config file missing, invalid, or not writable
wizard_completed flag not set

Solutions:

Check config exists and is valid JSON (use your actual install path):

cat ~/helixscreen/config/settings.json | jq .

If the file is missing or invalid, the wizard will run. After completing the wizard, verify:

grep wizard_completed ~/helixscreen/config/settings.json
# Should show: "wizard_completed": true

Check config directory is writable:

ls -la ~/helixscreen/config/
# The helixscreen process needs write access

Create fresh config from template:

cp ~/helixscreen/config/settings.json.template \
   ~/helixscreen/config/settings.json

Note: Copying the template creates a valid config but with wizard_completed: false, so the wizard will still run once to configure your printer.

Settings not saving

Symptoms:

Changes revert after restart
Config file unchanged

Solutions:

Check config directory is writable:

# Test write access (use your actual install path)
touch ~/helixscreen/config/test && rm ~/helixscreen/config/test
echo "Write OK"

Check disk space:

df -h

Check for filesystem errors:

dmesg | grep -i "read.only\|error\|fault"

Try manual edit to verify:

sudo nano /opt/helixscreen/config/settings.json
# Make change, save, restart
sudo systemctl restart helixscreen
# Check if change persisted

Wrong printer detected

Symptoms:

Wizard shows wrong printer model
Features missing or wrong

Solutions:

Re-run wizard:

Delete config: rm ~/helixscreen/config/settings.json
Restart: sudo systemctl restart helixscreen
Manually select correct printer in wizard

Manual configuration: Edit ~/helixscreen/config/settings.json to set correct printer type and features.

Flashforge Adventurer 5M Issues

The Flashforge Adventurer 5M (AD5M) has unique characteristics due to its embedded Linux environment and ForgeX/Klipper Mod firmware.

Screen dims after a few seconds

Symptoms:

Screen dims to ~10% brightness shortly after boot
Happens about 3 seconds after Klipper starts

Cause: ForgeX’s headless.cfg has a reset_screen delayed_gcode that sets backlight to eco mode.

Solution: The HelixScreen installer automatically patches /opt/config/mod/.shell/screen.sh to skip backlight commands when HelixScreen is running. If you installed manually or the patch didn’t apply:

# Check if patch is present
grep helixscreen_active /opt/config/mod/.shell/screen.sh

# If not present, re-run installer or manually add after "backlight)" line:
#     if [ -f /tmp/helixscreen_active ]; then
#         exit 0
#     fi

Black screen after boot

Symptoms:

Display stays black
SSH works, printer responds

Causes:

ForgeX not in GUPPY mode
GuppyScreen still running
Backlight not enabled

Solutions:

Check ForgeX display mode:

grep display /opt/config/mod_data/variables.cfg
# Should show: display = 'GUPPY'

Verify GuppyScreen is disabled:

ls -la /opt/config/mod/.root/S80guppyscreen
# Should NOT have execute permission (no 'x')

Check HelixScreen is running:

/etc/init.d/S90helixscreen status
cat /tmp/helixscreen.log

Service commands (SysV init)

AD5M uses SysV init, not systemd. Commands are different:

# Forge-X
/etc/init.d/S90helixscreen start|stop|restart|status
cat /tmp/helixscreen.log

# Klipper Mod
/etc/init.d/S80helixscreen start|stop|restart|status
cat /tmp/helixscreen.log

SSH/SCP notes

AD5M’s BusyBox has limitations:

# Use legacy SCP protocol (no sftp-server)
scp -O localfile root@<printer-ip>:/path/

# Use IP address, not hostname (mDNS may not resolve)
ssh root@192.168.1.67

# Extract zip archives with unzip
unzip archive.zip

# Alternative: use rsync if available
rsync -avz localfile root@<printer-ip>:/path/

Windows users: `scp -O` not supported

Windows 11’s built-in OpenSSH does not support the -O flag. Use one of these alternatives:

WSL (recommended) — Open a WSL terminal (Ubuntu, Debian, etc.) and run all commands exactly as shown in the install guide. Everything works natively.
WinSCP (free GUI) — Download from winscp.net. When connecting, set the protocol to SCP (not SFTP). Then drag and drop files to the printer.
PuTTY pscp (free command-line) — Download from putty.org. Use pscp instead of scp -O:
```
pscp helixscreen-ad5m.zip root@<printer-ip>:/data/
```

ForgeX not installed

Symptoms:

Installer fails or skips ForgeX configuration
HelixScreen runs but backlight doesn’t work

Solution: HelixScreen requires ForgeX to be installed first. Install ForgeX following their instructions, verify GuppyScreen works, then run the HelixScreen installer.

Restoring GuppyScreen

To go back to GuppyScreen:

# Automated (recommended)
curl -sSL https://raw.githubusercontent.com/prestonbrown/helixscreen/main/scripts/install.sh | bash -s -- --uninstall

# Manual
/etc/init.d/S90helixscreen stop
rm /etc/init.d/S90helixscreen
rm -rf /opt/helixscreen
chmod +x /opt/config/mod/.root/S80guppyscreen
chmod +x /opt/config/mod/.root/S35tslib
reboot

Gathering Diagnostic Information

When reporting issues, gather this information. Most importantly, enable debug logging first so the logs contain enough detail to diagnose the problem.

Enabling Debug Logging

By default, HelixScreen only logs warnings and errors. To capture useful diagnostic information, you need to temporarily enable debug-level logging, reproduce the problem, then collect the logs.

Quickest method: Go to Settings > System > Log Level and select Debug. This takes effect immediately with no restart needed. Remember to set it back to Warn when done.

Verbosity levels:

Flag	Level	What it captures
(none)	WARN	Errors and warnings only (production default)
`-v`	INFO	Connection events, panel changes, milestones
`-vv`	DEBUG	State changes, API calls, component init (use this for bug reports)
`-vvv`	TRACE	Everything including LVGL internals (very verbose, rarely needed)

MainsailOS / Raspberry Pi (systemd)

Option A: Temporary override (recommended)

# Create a service override that adds debug logging
sudo systemctl edit --force helixscreen

Add these lines (replace the path with your actual install location):

[Service]
ExecStart=
ExecStart=/home/biqu/helixscreen/bin/helix-launcher.sh --debug

Then restart:

sudo systemctl daemon-reload
sudo systemctl restart helixscreen

Option B: One-shot manual run

Stop the service and run manually with console output:

sudo systemctl stop helixscreen
cd ~/helixscreen   # or /opt/helixscreen
sudo ./bin/helix-launcher.sh --debug --log-dest=console
# Reproduce the issue, then Ctrl+C to stop

Option C: Environment variable

Add to the service file:

[Service]
Environment="HELIX_LOG_LEVEL=debug"

Flashforge Adventurer 5M / Forge-X (SysV init)

# Stop the running service
/etc/init.d/S90helixscreen stop   # or S80helixscreen for Klipper Mod

# Run manually with debug output
cd /opt/helixscreen
./bin/helix-launcher.sh --debug --log-dest=console 2>&1 | tee /tmp/helix-debug.log
# Reproduce the issue, then Ctrl+C to stop

# Restart the service normally when done
/etc/init.d/S90helixscreen start

After collecting logs

Remove the debug override to restore normal performance:

# MainsailOS: remove the override
sudo systemctl revert helixscreen   # or: sudo rm /etc/systemd/system/helixscreen.service.d/override.conf
sudo systemctl daemon-reload
sudo systemctl restart helixscreen

Important: Debug logging increases CPU usage and log volume. Don’t leave it enabled in production.

System Information

# HelixScreen version (use your actual install path)
~/helixscreen/bin/helix-screen --version

# OS version
cat /etc/os-release

# Hardware
cat /proc/cpuinfo | grep Model
free -h

Collecting Logs

MainsailOS (systemd):

# Recent logs (last 200 lines, with timestamps)
sudo journalctl -u helixscreen -n 200 --no-pager -o short-iso

# Logs since last restart
sudo journalctl -u helixscreen --since "$(systemctl show helixscreen --property=ActiveEnterTimestamp --value)" --no-pager

# Errors only (useful for a quick summary)
sudo journalctl -u helixscreen -p err --no-pager

# Follow live (while reproducing the issue)
sudo journalctl -u helixscreen -f

Flashforge Adventurer 5M (SysV init):

# Full log file
cat /tmp/helixscreen.log

# Last 200 lines
tail -200 /tmp/helixscreen.log

# Follow live (while reproducing the issue)
tail -f /tmp/helixscreen.log

Configuration

# Current config (sanitize API keys before sharing!)
# Pi: ~/helixscreen/config/ or /opt/helixscreen/config/
cat ~/helixscreen/config/settings.json

Display Information

# Framebuffer
ls -la /dev/fb*

# DRM devices
ls -la /dev/dri/

# Input devices
ls -la /dev/input/
cat /proc/bus/input/devices

Getting Help

Check Existing Resources

This troubleshooting guide - search for your symptoms
FAQ - common questions
GitHub Issues - known problems
HelixScreen Discord - ask the community for help

Opening a New Issue

If you can’t find a solution, open a GitHub issue with:

Required Information:

HelixScreen version (helix-screen --version)
Hardware (Pi model, display type)
What you expected to happen
What actually happened
Steps to reproduce

Helpful Additions:

Debug log output (enable debug logging first, then reproduce the issue)
Screenshots if visual issue
Config file (remove API keys/sensitive data)

Example Issue Format:

## Environment
- HelixScreen version: 1.0.0
- Hardware: Raspberry Pi 4 4GB
- Display: Official 7" touchscreen
- OS: MainsailOS 1.2.0

## Problem
Cannot connect to printer after WiFi change.

## Expected
Should connect to Moonraker on 192.168.1.100

## Actual
Shows "Connection failed" error

## Steps to Reproduce
1. Change WiFi network
2. Update config with new IP
3. Restart helixscreen service
4. See error

## Logs

[error] [Moonraker] Connection refused: 192.168.1.100:7125

## Configuration
```json
{
  "printer": {
    "moonraker_host": "192.168.1.100",
    "moonraker_port": 7125
  }
}

---

*Back to: [User Guide](/docs/) | [Installation](/docs/installation/)*

Troubleshooting

Table of Contents

Quick Debugging Guide

Startup Issues

HelixScreen crashes immediately (segfault)

”No display device found”

Logs are empty or not appearing

Connection Issues

”Cannot connect to Moonraker”

“Connection lost” during print

WiFi won’t connect

WiFi permission denied

SSL/TLS certificate errors

Display Issues

Black screen on startup

Wrong screen size or resolution

Resolution stuck at the wrong size, or -s has no effect

Display upside down or rotated

Colors are wrong (red and blue swapped)

5GHz WiFi networks not showing

Touch Input Issues

Touch not responding

Touch Feel — Which Setting Do I Tune?

Taps Register as Swipes

Unintended Clicks While Scrolling

Accidental Button Presses After Scrolling

Touch Input is Inaccurate

Touch is offset from visual elements

Calibration doesn’t help — touches still wildly off

Print Issues

Files not appearing

Print won’t start

Can’t pause or cancel print

AMS/Multi-Material Issues

AMS slots not detected

Load/Unload fails

Spoolman Issues

Spoolman not showing

Spool data not syncing

Only some spools showing in Spoolman lists

Calibration Issues

Input Shaper measurement fails

Screws tilt shows wrong adjustments

Performance Issues

UI feels slow or laggy

High memory usage

Configuration Issues

First-run wizard keeps appearing

Settings not saving

Wrong printer detected

Flashforge Adventurer 5M Issues

Screen dims after a few seconds

Black screen after boot

Service commands (SysV init)

SSH/SCP notes

Windows users: scp -O not supported

ForgeX not installed

Restoring GuppyScreen

Gathering Diagnostic Information

Enabling Debug Logging

MainsailOS / Raspberry Pi (systemd)

Flashforge Adventurer 5M / Forge-X (SysV init)

After collecting logs

System Information

Collecting Logs

Configuration

Display Information

Getting Help

Check Existing Resources

Opening a New Issue

Resolution stuck at the wrong size, or `-s` has no effect

Windows users: `scp -O` not supported