FLYOS-FAST Common Issues and Troubleshooting

This page consolidates information about FLYOS-FAST system limitations, configuration paths, update methods, and common faults. For complete operational steps for specific features, please follow the links to the corresponding documentation to avoid duplicating maintenance efforts in the FAQ.

Recommended Troubleshooting Order

1. Record the complete error message displayed on the webpage or terminal, not just the last line.
2. Identify which configurations, plugins, or system options were modified before the issue occurred.
3. Check disk space, service status, and corresponding logs.
4. Before restarting services or the host machine, confirm that the printer is not executing print, heating, or motion tasks.

System and Account

Why can I only use the root user?

FLYOS-FAST is a streamlined system designed for print control devices and uses single-user management. root is the only interactive administrative account. The system does not support creating other users or switching to them.

Why can't I use apt or dpkg?

FLYOS-FAST does not provide a traditional Linux distribution package management environment, so the following commands cannot be used to install or update software:

apt update
apt install
dpkg -i

Do not copy software packages or system libraries from other Linux systems. Additional dependencies should be explicitly provided by plugin installation tutorials; if common dependencies are missing, please report this to technical support.

Why does the system directory appear as read-only?

The core system uses a read-only file system and is updated uniformly via full images or OTA. Do not attempt to remount the root directory and directly modify system files, as this may cause update failures or loss of changes after reboot.

User configurations, plugins, and print data should be saved in persistent directories.

Files and Configuration

Where are common files stored?

Content	Klipper Mode Path	Description
Printer Configuration	/usr/share/printer_data/config/	Contains printer.cfg, Moonraker, and camera configuration
G-code Files	/usr/share/printer_data/gcodes/	File entry point for web uploads and USB drive printing
Run Logs	/usr/share/printer_data/logs/	Klipper, Moonraker, screen, and camera logs
Plugins and Source Code	/data/	Custom plugins should be uniformly stored here
Klipper Source Code	/data/klipper/	System pre-installed Klipper directory
Build Output	/data/klipper/out/	Output directory after firmware compilation is complete

The data directory for RRF mode is /opt/dsf/. Do not mix Klipper and RRF configuration paths.

RRF configuration paths and common errors: View RRF mode troubleshooting

Which directories are persistently saved?

The system saves /etc, /data, /root, as well as the data directory of the current printing mode. Even though these directories are retained, printer configuration should still be backed up separately before performing an OTA update or re-flashing.

How do I modify FLYOS-FAST system configuration?

System model, network, screen, and service toggles are uniformly managed in FlyOS-Conf/config.txt. After the system boots, they can also be modified via .flyos-config/sys-config.conf on the web page.

Configuration methods and scope of effect: View the FLYOS-FAST system configuration guide

Why do my changes not take effect after modification?

Different configurations require different actions to take effect:

Modified Content	Action Required
printer.cfg and Klipper configuration snippets	Click Save & Restart on the web page
moonraker.conf	Restart Moonraker
config.txt or sys-config.conf	Restart the entire host machine
Plugin source code or symbolic links	Restart the corresponding service according to the plugin tutorial

If the changes still do not take effect after restarting, please confirm that the file has been saved, that there are no duplicate configuration items, and check the corresponding service logs.

RRF Mode

What should I do if DCS repeatedly disconnects in RRF mode and prompts M550 machine name mismatch?

The following phenomena occur in RRF mode:

• The DWC webpage repeatedly displays Connection interrupted and DCS has been stopped.
• The startup log contains Error in start-up file config.g line 3: M550: Machine name must consist of the same letters and digits as configured by the Linux hostname.
• DCS (Duet Control Server) fails to start properly, and the webpage cannot connect.

Cause

RRF requires that the machine name set by M550 P"..." in config.g must be exactly the same as the Linux system hostname (containing only the same letters and digits). When the two do not match, DCS will refuse to start and repeatedly crash and reconnect.

printer_name is only used to initialize the hostname on first boot. If the hostname was subsequently modified manually without synchronously updating config.g, or if config.g was copied from another device, this error will occur.

Troubleshooting and Fix Steps:

1. Connect to the host machine via SSH and check the current Linux hostname:

   hostname

2. Check the current value of M550 in the RRF configuration file:

   cat /opt/dsf/sd/sys/config.g | grep M550

3. Change M550 to match the hostname. For example, if the hostname is fly-c5, it should be changed to:

   M550 P"fly-c5"

4. After saving the file, restart DCS from the DWC webpage, or directly restart the host machine.

Name Character Restrictions

The machine name in M550 can only contain letters and digits, and cannot include spaces, underscores, Chinese characters, or other special characters. If you need to modify the hostname, you should synchronously update M550 in config.g to keep both consistent.

Where are the configuration files in RRF mode?

All RRF configuration files are located in /opt/dsf/sd/sys/ directory. The main files include:

File	Purpose
config.g	Main startup configuration file, containing core settings such as M550 (machine name)
board.txt	Board-level configuration (network, SPI, etc.)
deploy.d	Deployment script directory

G-code files are stored in /opt/dsf/sd/gcodes/, and files printed from USB drives are also mounted to this path. Do not mix the Klipper configuration path (/usr/share/printer_data/) with RRF.

Plugins and Python Environment

Why can't I find ~/klippy-env/bin/python?

FLYOS-FAST uses the system Python and does not use the common klippy-env virtual environment. You should change the Python interpreter and Klipper paths in commands to the actual system paths. For example, when querying the CAN UUID, use:

python /data/klipper/scripts/canbus_query.py can0

Do not just replace the Python command while keeping the incorrect ~/klipper/ path.

Where should plugins be installed?

Plugin repositories should be placed uniformly under /data/. When adding extension files to Klipper, prefer using symlinks, and first confirm the file names and dependencies required by the plugin tutorial. Do not bulk-copy entire plugin directories into Klipper.

Installation Rules and Existing Plugin Tutorials: View the Plugin Installation Instructions

What should I do if a plugin doesn't take effect after installation?

Check the following in order:

1. Whether the network pull step completed successfully.

2. Whether the plugin files actually exist in /data/.

3. Whether the symlink points to the correct file:

   readlink -f /data/klipper/klippy/extras/plugin-file.py

4. Whether printer.cfg loads the plugin configuration.

5. Whether the Klipper log shows errors about missing modules, dependencies, or configuration items.

Do not disable safety configurations or turn off Klipper's temperature, endstop, and heater protection just to bypass error messages.

Web Interface and Network

What are the various web interface entry points?

Feature	Address	Usage Conditions
Fluidd or Mainsail	http://device-IP/	Klipper mode started normally
OTA management page	http://device-IP:9998/	Host machine network is normal
GoCam management page	http://device-IP:8080/	GoCam is enabled

Why can't I access device-IP:9999?

FLYOS-FAST does not provide the fly-tools web service by default, so port 9999 not responding is normal. System configuration and firmware operations should use the corresponding FLYOS-FAST documentation and SSH commands.

How do I check when the main web page is inaccessible?

1. Confirm that the computer and the host machine are on the same local network.

2. Check the device address in the router to avoid continuing to use a stale old IP.

3. Check the current network address via SSH:

   ip -br addr

4. Check for services that failed to start:

   systemctl --failed --no-pager

5. If SSH is also unreachable, first check whether the system has completed booting, then troubleshoot the network cable, Wi-Fi configuration, and power supply.

SSH Connection Methods: View Connecting to the Host Machine via SSH

Printing, USB Drives, and Cameras

The USB drive is recognized, but printing won't start. What should I do?

Confirm the file system, G-code file extension, available local space, and file encoding. Some non-UTF-8 G-code files may display as "uploaded locally successfully" but fail to start printing from a USB drive.

USB Printing and Encoding Troubleshooting: View the USB Printing Feature Usage Guide

What should I do if the camera has no image?

First confirm that the camera supports the UVC protocol, then check whether the camera service is enabled, whether the device node is correct, and whether the resolution is supported by the camera. Do not start two services that occupy the same camera simultaneously.

Camera connection and configuration: View camera connection and usage

What should I do if no image is generated for timelapse?

First, directly access the snapshot URL in your browser to confirm that a single image can be returned. If the camera service changes, you need to synchronously update the snapshoturl in moonraker.conf.

Snapshot URL and log troubleshooting: View timelapse functionality

Where should I start troubleshooting after Klipper reports an error?

Prioritize recording the raw error displayed on the webpage, and check the first exception that appears in klippy.log. The disconnection or restart prompt that appears last is usually just a subsequent symptom and may not be the root cause.

Klipper error index: View common Klipper errors

Logs and Technical Support

Where are the common logs located?

Log	Path
Klipper	/usr/share/printer_data/logs/klippy.log
Moonraker	/usr/share/printer_data/logs/moonraker.log
KlipperScreen	/usr/share/printer_data/logs/klipperscreen.log
Crowsnest	/usr/share/printer_data/logs/crowsnest.log
GoCam	/usr/share/printer_data/logs/gocam.log
U-disk auto-mount	/var/log/flyos-auto-mount.log

To view only recent content, you can use:

tail -n 100 /usr/share/printer_data/logs/klippy.log

Check the status of the main services:

systemctl status klipper moonraker --no-pager

Check system resources:

uptime
free -h
df -h

What should I provide when contacting technical support?

Please provide as much as possible in one go:

• The specific models of the host machine and the mainboard.
• The FLYOS-FAST version number.
• The operations performed or modifications made before the issue occurred.
• A screenshot of the complete error displayed on the webpage.
• The complete klippy.log, moonraker.log, or corresponding service logs.
• Whether the issue can be stably reproduced, and whether it still exists after a reboot.

Do not only provide the truncated last few lines of the log, as the actual first error may not be visible. Before sending configuration files and logs, please remove sensitive information such as Wi-Fi passwords, cloud service credentials, and tokens.

Logs and Technical Support

Where are common logs located?

Log	Path
Klipper	/usr/share/printer_data/logs/klippy.log
Moonraker	/usr/share/printer_data/logs/moonraker.log
KlipperScreen	/usr/share/printer_data/logs/klipperscreen.log
Crowsnest	/usr/share/printer_data/logs/crowsnest.log
GoCam	/usr/share/printer_data/logs/gocam.log
USB Auto-mount	/var/log/flyos-auto-mount.log

To view only recent content, you can use:

tail -n 100 /usr/share/printer_data/logs/klippy.log

To check the status of main services:

systemctl status klipper moonraker --no-pager

To check system resources:

uptime
free -h
df -h

What should you provide when contacting technical support?

Please provide as much of the following as possible at once:

• The specific models of the host board and mainboard.
• The FLYOS-FAST version number.
• The operations performed or modifications made before the issue occurred.
• A full screenshot of the webpage error.
• The complete klippy.log, moonraker.log, or corresponding service log.
• Whether the issue can be reliably reproduced, and whether it persists after a reboot.

Do not provide only the truncated final lines of logs, as the first actual error may not be visible. Before sending configurations and logs, please remove sensitive information such as Wi-Fi passwords, cloud service credentials, and tokens.