Skip to content

Troubleshooting

Find what you see below. Each entry names the likely cause and links to the page that owns the fix. Messages may appear in the terminal or the detailed log. The launcher prefixes visible errors with FPLinux:; lower-level log entries may use fplinux run: or fplinux ssh:. <target> stands for your phone’s target name, such as nokia-ta1618.

The loader stops before it asks for the phone

Section titled “The loader stops before it asks for the phone”
Message What to do
fplinux ssh: required host tool is missing: NAME Install the PC tools listed in Run FPLinux.
fplinux run: GNU stdbuf is required (install coreutils …) Install GNU coreutils.
fplinux: current build is missing or invalid; rebuild it: … Run the build command it prints. Pass the same profile and build type to build and run.

The phone did not start in boot ROM mode. It was already on, the boot key was not held while you connected USB, or the cable does not carry data. The loader stops when its 300-second connection deadline expires.

Disconnect USB, power the phone off, start the loader again and connect the phone only when it asks, holding the boot key from your phone page. See Run FPLinux.

The phone was switched on normally, without the boot key. Disconnect USB, power the phone off and start again from the loader as described in Run FPLinux.

Access to the phone’s USB device is denied

Section titled “Access to the phone’s USB device is denied”
Output
fplinux run: BootROM USB 1782:4d00 is not readable and writable by the current user; install the documented udev rule and reconnect the phone

Install the USB rules from Allow USB access, then disconnect the phone and connect it again.

Follow the loader’s instructions. On Linux, the UMS9117 loader can print RAM loader attempt N/3 exited with status … and ask for a fresh connection. Disconnect the phone, power it off and reconnect in boot ROM mode when asked. These attempts share one deadline, so it can stop before all three are used. Qin and ordinary Windows upload failures stop the command instead; start the launcher again before connecting the powered-off phone. Keep the complete loader output for a problem report.

The loader stops after the phone was loaded

Section titled “The loader stops after the phone was loaded”

The load finished, but the phone did not hand over to Linux in time. The loader stops with a message such as fplinux run: bridge did not acknowledge the Linux transition before the deadline or fplinux run: BootROM USB did not disconnect before the deadline. Disconnect USB, power the phone off and start again from the loader. If it happens again, keep the complete output for a problem report.

The runtime log records Bridge acknowledged the Linux transition; waiting up to 60 seconds for Linux USB-NCM 0525:a4a6. and the launcher later stops with fplinux ssh: the exact USB-NCM SSH session did not become ready before the deadline. The launcher prints the log’s exact path when it starts.

The loader did not authenticate the Linux USB session in time. Check that the PC has a network manager that runs IPv4 DHCP on a newly attached USB network interface, such as NetworkManager. While the loader waits, look for a new USB network interface with an IPv4 address:

PC
ip -4 -brief address

See Run FPLinux for the PC requirements. If those requirements are met and a fresh load fails again, keep the complete output for a problem report.

No load of this target has reached a ready session on this PC, or you passed a different target name. Select the same target, profile and build type. Start the phone with ./fplinux run <target> if no session exists; this command also prepares required UMS9117 RAM data on first use. See Run FPLinux.

Another launcher is already open. Close it before starting this one. means another copy is using the same local data directory. It may be waiting for a phone or serving an SSH shell. Close that launcher before starting another. Exiting an SSH shell leaves Linux running; use the same launcher to reconnect.

Preparation asks you to keep the phone powered

Section titled “Preparation asks you to keep the phone powered”

Storage is still mounted or used as swap, or the runtime could not verify its state. Reader access is retained under reader/session/ in the private data directory. Keep power connected and release storage safely as described in Power. Cancelling the launcher does not power the phone off.

fplinux ssh: the current USB-NCM SSH session did not reconnect before the deadline means the phone is no longer reachable over the cable. If the phone has a battery and is still on, plug the cable back in and run the command again. Without a battery, unplugging the cable switched the phone off and ended the session; start a fresh load. See Reconnect after unplugging.

console or verify refuses the running phone

Section titled “console or verify refuses the running phone”

current SSH session exposes a different kernel identity means the phone runs a different build from the one you selected:

  • Pass the same profile and build type that started the session. For a microSD system card, use the profile selected in Boot from the card.
  • If verify reports build output is stale; rebuild it, your checkout changed inputs that affect the selected runtime after the build. Rebuild, then start a fresh session to run the new build. Changes only to documentation or optional APKs do not require a fresh RAM load.

See Check which build is running.

fplinux ssh: interactive SSH requires a terminal; use --exec for a non-interactive command. Without a terminal, run single commands with --exec, as shown in Run one command.

fplinux ssh: upload destination is missing or does not have enough free space. The destination on the phone must be an absolute path in a directory that already exists. /tmp uses the phone’s small RAM; on phones with supported microSD storage, copy large files to a mounted microSD card instead. Check the phone checklist before using a card. See Copy files.

  • The graphical session blanked the screen. Press and release a key to wake it, then unlock if prompted. See Lock and screen timeout.
  • The brightness is 0. Restore it from a shell opened from your computer with fplinux-brightness set 7. See Screen brightness.
  • The phone is asleep. Use the key or armed RTC alarm listed as a verified wake source on your phone page. Ordinary keypad keys do not wake a sleeping phone, and keys pressed during sleep are lost. See Sleep.
  • The loader printed Headless target. A target created for a phone that is not supported yet shows no screen; use the phone from your computer. See Bring up a new phone.

Inspect rc-service fplinux-session status and /var/log/fplinux-session.log from the USB shell. Save any recoverable work before restarting the service, because restarting closes graphical applications. Terminal opens from the graphical application catalog.

Press # to change letter case or return from 123 to letters. Hold it to switch between letters and digits; hold * to change the input language. These gestures work in graphical text fields and Terminal; see Type text. Check the phone’s input status if no keypad text appears; the USB shell remains available for control.

A keyboard layout is unavailable in Terminal

Section titled “A keyboard layout is unavailable in Terminal”

The graphical session loads installed keyboard layouts when it starts. Save your work and restart the session after adding a layout package. It accepts up to three registered layouts beside US. The initial keypad language is selected separately in Settings → Input; see Terminal keypad input. See Keyboard layout packages for external keyboard layouts.

Check the output and automatic-routing entries in your phone checklist first.

  • The volume is low. UMS9117 headphone and speaker outputs start at 1 after every boot. Qin uses a single Master control. Follow the controls for your platform in Volume.
  • Headphones are plugged in. Where automatic routing is supported, any plug in the socket moves playback away from the speaker.
  • The speaker controls are missing. Check the phone’s device data and audio support. UMS9117 RAM launches require all declared data; after explicitly replacing it, start a fresh RAM session. A system card must be rebuilt and written with the new data.
  • FM radio is on. A file cannot play while FM radio plays, and the other way round.
  • Speaker-based vibration: headphone sound is muted while the phone vibrates and for about a second afterwards.

See Sound and recording.

Stop using FM and cold-boot the phone. Until then the phone cannot sleep. See If the receiver stops responding.

  • The image has no Bluetooth. Bluetooth needs firmware from the same phone’s device data. UMS9117 RAM runs prepare required data automatically. Qin’s optional original-file import and microSD system cards need an explicit rebuild. Check the phone’s support status before expecting Bluetooth to work.
  • Bluetooth is off. It starts powered off; turn it on with bluetoothctl power on.
  • The other device remembers an old pairing. After every new RAM load the phone has forgotten its pairings. Run remove PHONE-MAC on the other device, then pair again. A microSD system card keeps pairing records between boots.

Follow the pairing steps in the given order, one command at a time, as in Bluetooth.

A sleep request fails while the FM receiver is on, including during a scan, and while a Bluetooth connection is active. Turn FM off or disconnect the Bluetooth device first. After an FM command has timed out, sleep fails until a cold boot. See Sleep.

  • Check that your phone supports microSD access.
  • Card detection has no fixed delay. Wait until /dev/mmcblk0 appears.
  • If the slot is under the battery, insert the card before starting the phone. Follow the phone page’s card-access rules.
  • On Nokia TA-1618, after removing an unmounted card, wait until /dev/mmcblk0 has disappeared before you insert another one. Other phones keep the card installed from boot to shutdown.
  • Data cards must use FAT32 or ext4.

See microSD card.

  • Check that your phone supports a microSD system-card profile.
  • The image must come from a build of that profile for your exact target.
  • FPLINUX.img.xz must be decompressed and written to the whole card device, not to a partition or copied as a file, and read back for comparison. See Prepare the card.
  • Start the loader with the same profile and build type, following Boot from the card.
  • Leave the card in the phone for the whole session.

See microSD system card.

Message What to do
Kern is not ready for this checkout; run ./fplinux setup Run ./fplinux setup with network access.
the pinned build environment is not ready; run ./fplinux setup Run ./fplinux setup with network access.
Kern cannot map the package builder; configure newuidmap/newgidmap … Install newuidmap and newgidmap and give your user subordinate UID and GID ranges.
the build interface currently supports Linux hosts only Build on a Linux PC.
the pinned build environment currently targets linux/amd64 Build on an x86-64 PC.

See What you need.

Show the failed part of the last run:

PC
./fplinux logs show latest --command setup --failed
  • The host cannot be reached or the request times out. Check the PC’s connection and retry after the network or server recovers.
  • An exact package URL returns 404. The repository may have removed that package revision. Retrying cannot restore it. Restore the matching dependency snapshot or release inputs if you have them; otherwise report the missing URL.
  • NAME SHA256 mismatch: expected …, received …. The downloaded bytes differ from the pinned input and are rejected. Restore a matching dependency snapshot or report the URL and expected/received hashes. Do not disable verification or substitute a different package version.

Builds use local inputs and never download dependencies. The command names the missing input and required setup selection, or reports that the pinned environment is absent or out of date. With matching dependency inputs restored, run the reported setup command with --offline, for example ./fplinux setup nokia-ta1618 --offline. A complete local snapshot can also restore its saved environment. Without saved inputs, run the selected setup command with network access, then retry the build. See Dependency snapshots and Build without network access.

A build fails or the PC runs out of memory

Section titled “A build fails or the PC runs out of memory”

Read the failed stage with ./fplinux logs before changing settings. A build that reaches its own memory limit can fail while the PC still has free RAM: raise --memory-mib only when the host has enough room. If the whole PC is short of RAM, close other memory-heavy programs or reduce parallel jobs. Recreating the build environment does not fix either memory limit. See Build FPLinux and Debugging.

Interrupted commands can leave staged workspaces behind. ./fplinux prune lists them and ./fplinux prune --apply removes them. See Free disk space.

Report a problem with the phone, target, profile, build type and the complete output of the failing command.