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 configurations
G-code files	/usr/share/printer_data/gcodes/	File entry point for web uploads and USB printing
Runtime logs	/usr/share/printer_data/logs/	Klipper, Moonraker, screen, and camera logs
Plugins and source code	/data/	Custom plugins should be placed here uniformly
Klipper source code	/data/klipper/	Pre-installed Klipper directory
Build artifacts	/data/klipper/out/	Output directory after firmware compilation

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

Which directories are persisted?

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

How do I modify FLYOS-FAST system configuration?

System model, network, screen, and service switches are centrally managed in FlyOS-Conf/config.txt. After the system boots, they can also be modified via the .flyos-config/sys-config.conf file in the web interface.

Configuration Methods and Effective Scope: View the FLYOS-FAST System Configuration Guide

Why didn't my configuration change take effect?

Different configurations require different actions to take effect:

Modified Content	Action to Take Effect
printer.cfg and Klipper config snippets	Execute Save & Restart in the web interface
moonraker.conf	Restart Moonraker
config.txt or sys-config.conf	Restart the entire host machine
Plugin source code or symlinks	Restart the corresponding service according to the plugin tutorial

If the change still hasn't taken effect after a restart, confirm that the file has been saved, that configuration items are not defined multiple times, and check the corresponding service logs.

System Updates and Firmware

How should I update the system?

FLYOS-FAST should be updated via system OTA or by re-flashing the official image for the corresponding device. Do not use third-party system upgrade scripts to replace core files.

Online and USB Updates: View the OTA System Update Guide

Re-flashing the System: View the System Image Flashing Tutorial

Will OTA delete my printer configuration?

Normal OTA updates will preserve /data and the printer data directory. However, the following situations may still cause configuration anomalies:

• The user manually replaced Klipper, Moonraker, or other pre-installed components.
• Custom files overshadow new files provided by the OTA update.
• Power interruption during the update process.
• Insufficient disk space or a corrupted file system before the update.

Download or copy a backup of printer_data/config before updating. Keep the power supply stable during the update and restart process, and do not perform print operations.

Can I update Klipper or Moonraker individually?

This is not recommended. The Klipper, Moonraker, web interface, and screen services in the system are adapted to work together. Replacing a single component individually may break paths, extension interfaces, or update mechanisms. Please use the system's integrated update method.

What should I do if there is an MCU version mismatch after OTA?

OTA only supports automatic USB firmware updates for the FLY-C8, FLY-C5, FLY-C8P, and FLY-GEMINI V3 mainboards. Other mainboards, CAN firmware, tool boards, and other external MCUs do not support automatic updates and must be flashed manually according to the corresponding product tutorial.

Automatic Update Scope and Checking Methods: View the MCU Firmware Update Instructions After OTA

Where do I find the files after firmware compilation is complete?

The build artifacts are located at:

/data/klipper/out/

The actual file may be klipper.bin or klipper.uf2, depending on the MCU architecture and bootloader configuration.

Firmware Compilation Instructions: View the Klipper Firmware Compilation Tutorial

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.