Troubleshooting

The desktop closing on its own, floating windows that will not open, sound that stops, applications that look wrong, and how to send a useful diagnostic.

The desktop closes on its own

If the Linux desktop disappears while you are using it, and Breadstick says the session was closed to free memory, the message is usually wrong about the reason. It is normally not memory. It happens most often a short time after opening a web browser.

What is actually happening. Android limits how many processes a single app is allowed to have running. On most devices the limit is 32. A Linux desktop is made of processes: the window manager, the panel, the file manager, the sound server and every application each account for one or more, and as far as Android is concerned all of them belong to Breadstick. When the total goes over the limit, Android kills them. It does not stop at the few that crossed the line, and the process that hosts the entire Linux system is one of the ones it can pick, which is why everything closes at once rather than a single application quitting.

A browser is usually what tips it over. Chrome can run a dozen processes on its own, one or more per site you have open.

What Breadstick already does. From version 1.0.2 the desktop starts fewer background services, and the browser is set up to share processes between tabs instead of starting one per site. That keeps a normal session comfortably inside the limit. Check you are up to date first, because this is the fix for most people:

• Updates on the Linux desktop, or
• sudo apt update && sudo apt upgrade in the Terminal

Watch the count. While a Desktop or Floating session runs, Breadstick counts its processes the way Android does. A banner appears over the desktop or the Apps drawer from 27 and turns red at 30, and at 30 Android's notifications say so too, since in Floating mode the Breadstick window is usually out of sight. Don't show again on the banner turns the warnings off, and Warn me under Settings, Troubleshooting turns them back on. The first line of Troubleshooting shows the live count, and the resource monitor charts it. On a device where the limit has been removed, the warnings stay quiet. On a computer running Android, such as a Googlebook, they start earlier, because the system's own virtual machines take part of the limit.

If it still happens. Close what you are not using, browser tabs first. Every open application costs at least one process, and heavy applications cost several. When Android does close the session, Breadstick says so and can restart it, and in Floating mode it offers to reopen the apps you had open: see If Android closes Linux.

Apps opened outside the desktop, from Floating windows, the Apps drawer or a Terminal tab, now share the session's system services. That saves the processes some of them used to start for themselves, but it also means that when Android closes the session, most of those apps close with it.

Browser extensions count too. Every extension that works in the background, such as a password manager or an ad blocker, runs in a process of its own for as long as the browser is open, and no browser setting lets them share. Signing in to Chrome installs the extensions from your other computers all at once, which can be enough by itself to close the session. Keep the extensions you use in Linux and remove the rest from the Linux browser, or choose not to sync extensions in Chrome's settings.

Removing the limit entirely. Android has a setting that turns this behavior off. On some devices, Developer options has a switch for it, Disable child process restrictions. But on some Android 17 devices that switch did not take effect, while the command below did, so the command is the reliable way. Set it once from a computer with ADB, with the device connected by USB and USB debugging enabled in Developer options, or connected over Wireless debugging:

adb shell settings put global settings_enable_monitor_phantom_procs false

Please understand what this does before using it. The limit is there to stop applications from quietly running processes in the background and draining the battery, and turning it off removes that protection for every app on the device, not just Breadstick. It is a reasonable thing to do on a device you use for development work, and a poor idea on a phone you depend on. It may also be switched back on by an Android update, in which case run the command again.

Breadstick cannot change this setting itself. No app can; that is the point of it.

Steam needs the limit off: a desktop and Steam together need more processes than it allows, so the Steam card in Recommended apps refuses to install until the limit is off.

The resource monitor

Resource monitor, under Monitor on the home screen, shows what Breadstick and its Linux system take from the device, live. It is free, and it is also under Settings, Troubleshooting. The card on the home screen carries a one-line summary.

It takes a reading every two seconds and draws the last five minutes, and only while the monitor or its home screen card is on screen, so it costs nothing the rest of the time. Devices report battery current in different ways, so treat the watts as a guide.

The process count here includes everything Linux runs, Terminal tabs too. It is the number to watch if the desktop has been closing on its own, and the Processor, Power and Temperature tiles show what is going on when the device slows down or gets hot.

Floating apps open full screen, or not at all

On Samsung DeX, and on a Googlebook with Android's desktop windowing, floating windows work with no setup. On other Android devices, freeform windows are switched off by default and have to be enabled once:

1. Open Android Settings, then Developer options
2. Turn on Enable freeform windows
3. On some builds, also turn on Force activities to be resizable
4. Restart Breadstick

Desktop mode and the Terminal work without this. Breadstick detects the setting and points you at it when it is missing.

An application will not start

Start it from a terminal instead of the launcher. Running it by name shows you the error, which is usually a missing dependency or a message about something the application expects and cannot find here, such as a GPU or a systemd service. An application with a window needs a Desktop or Floating session running. To see why one fails, start it from Terminal on the Linux desktop in Desktop mode, or Terminal from the Apps drawer in Floating mode: both run it the way the launcher does.

If a package is half installed, use Repair under Environment on the home screen. It fixes package state without touching your files.

If the error names libbsl-shm.so, the program cannot load the helper Breadstick uses to speed up drawing. This is rare: programs built for Alpine Linux are the known case. Start that one program without the helper with env -u LD_PRELOAD followed by its name, or turn the helper off for the whole desktop with sudo touch /etc/breadstick/no-shm and restart the desktop. A line saying libbsl-shm.so "cannot be preloaded (wrong ELF class)" comes from 32-bit programs, which run normally and can ignore it.

LibreOffice says /proc is not mounted

Take the Linux system update: Settings, System updates, Check, then Upgrade all. From 1.0.13 Breadstick starts LibreOffice in a way that avoids the check behind that message. /proc is mounted; Android just does not let an app read the one file LibreOffice's launcher looks at.

Sound stopped

Sound inside Linux comes from a sound server (PulseAudio) that runs with the session. If it stops while the desktop keeps running, everything goes silent at once, and a browser started after that point tries to play through a sound card that does not exist. Breadstick now notices the server going away and restarts it on its own; Restart audio under Settings, Troubleshooting, does the same by hand. An application that had already gone silent may need to be closed and reopened to find the server again, and the same is true after any restart of the session.

Text appears as empty boxes

You are missing fonts for that language. Install the Fonts and languages pack from Recommended apps, which covers Chinese, Japanese, Korean and emoji. It is left out of the base system because of its size.

Everything is slow, or the device gets hot

Linux applications run on your device's own processor. Several heavy applications at once, a compile, or anything 3D will use everything available. The resource monitor shows how much of the processor Breadstick is using, and whether Android considers the device hot. Unless GPU acceleration is on, all graphics are drawn in software, so anything visually intensive is expensive. See the limits page.

An app draws wrongly with GPU acceleration

Turn it off for that app, or for everything, under Settings, Graphics. If an app draws wrongly has the details.

The desktop is tiny or enormous

Breadstick sizes the desktop from the density of the screen it is drawn on: a phone's own display, a tablet, or the monitor DeX is driving. Before 1.1.0 it used the phone's density for everything, which drew a giant desktop on an external 1080p monitor. If the size is still wrong for you, change the display scaling inside the Linux desktop's own settings.

Floating windows are tiny on a phone

Floating apps start at a scale chosen from the screen's density, so on a phone they open at 150% or 200%. To change one app, long-press it in the Apps drawer and pick Display scale; it applies the next time that app starts.

A Bluetooth keyboard types nothing in Linux apps

Check which on-screen keyboard is active. With Microsoft SwiftKey selected, a physical keyboard's keys do not reach Linux applications; with Gboard or Samsung Keyboard the same keyboard works. Switch in Android's Settings, under General management, then Keyboard list and default.

Scrolling goes the wrong way

Settings, under Input, has a reverse switch for the mouse wheel and another for the touchpad. They are separate on purpose: natural scrolling on a keyboard cover's touchpad and a wheel that scrolls the traditional way is a common combination. Two fingers on the touchscreen always move the content with them and have no switch.

Linux cannot look up names

Settings, under Network, shows which DNS servers Linux is using. The default follows your device, including a VPN's servers while one is connected. If you set custom servers and they stop answering, switch back to Same as this device. Fix internet in Linux under Troubleshooting rewrites the configuration from that setting.

Running out of space

The package cache grows as you install things:

sudo apt clean
sudo apt autoremove

Snapshots are large. If you keep several, they are usually the biggest thing you have.

Sending a diagnostic

Settings has Share diagnostics, which collects the session logs and opens a new email to hello@breadstick.io with them attached. It is far more useful than a description, especially for anything involving windows failing to appear.

Look at what it collected before sending. It is your log file and you should know what is in it.

Reporting something

hello@breadstick.io. Tell us the device, whether you were in Desktop, Floating or Terminal, and what you expected to happen. If the problem is a window that will not draw, the diagnostic is worth attaching.