Troubleshooting

Troubleshooting

Most of what looks broken here is either macOS being correct or a limitation stated honestly. This page separates the two. The first half is about one Mac; the second is about the fleet.

"Apple's container CLI wasn't found" — but it is installed

Almost certainly a PATH problem, and it used to be a real bug.

A GUI-launched app does not inherit your shell's PATH. LaunchServices hands a bundled app exactly /usr/bin:/bin:/usr/sbin:/sbin, and container lives in /usr/local/bin. Flotilla now looks there explicitly, and the message lists every directory it searched — so if it still happens, compare that list with which container in Terminal and set Binary path yourself in Settings.

To reproduce a GUI launch environment from a terminal:

env -i PATH=/usr/bin:/bin:/usr/sbin:/sbin build/Flotilla.app/Contents/MacOS/Flotilla

Launching from a terminal normally hides this class of bug, because your terminal has a rich PATH.

Everything says running, and nothing new will start

Two causes, and Flotilla names both:

• No kernel. A fresh install of container looks running and cannot start anything until a kernel is downloaded. Use Download Kernel in the banner.
• The service is an older build than the CLI. Upgrading container without restarting its service leaves run failing with no available interface strategy for network default. Flotilla shows both builds; Restart Container System, in the menu on the status bar's container dot, fixes it.

See First run for every state the preflight tells apart.

container keeps starting by itself — or does not

By default Flotilla starts the stopped service once after this Mac starts up, and never again that boot, so a stop you made stays a stop. If it starts at other times, check Settings ▸ Advanced ▸ Start container by itself; if you want it never to, choose Never. An admin can change this setting for a host, unless a profile locks it.

"Launch at login" will not stay on

Expected for a locally built app. SMAppService registration can be refused for an ad-hoc-signed bundle, and Scripts/make-app.sh signs ad-hoc. The row shows the real status — including awaiting approval — rather than a toggle that lies.

It works with a Developer ID signed build. If it is awaiting approval, approve Flotilla in System Settings ▸ General ▸ Login Items & Extensions.

The window is grey, or appearance looks mixed

Fixed, but if you see it: switching to another app and back used to correct it. The cause was two different mechanisms both writing window appearance and disagreeing intermittently — NSApp.appearance is only a fallback, and a window with its own appearance set ignores it.

One authority per property is why this is no longer possible.

A window opens at login even with the Dock icon off

Known limitation. With Show Dock icon off, the Dock icon correctly disappears but a window still opens at login. Three approaches were tried and none held.

Do not expect a fix before the app moves to a real Xcode project with an NSWindow delegate.

A machine will not boot

Use alpine. Ubuntu, Debian and Fedora do not boot as machines — each pulls ~100 MB, creates a record and dies. See Machines.

Machine settings saved but nothing changed

Correct behaviour. container machine set accepts changes on a running machine and applies them at next start. Flotilla says "Saved — still running on the previous values". Stop and start the machine, or use Apply and Restart.

I cannot edit a container's settings

There is nothing to edit. container 1.5 has no update subcommand, so no such operation exists. Use Run Again with Changes…, which prefills a create form — and note it does not carry environment variables or mounts, for the reason given in Containers.

A container is "running" and cannot be reached

If a banner says a network has lost its connection to this Mac, that is the cause: a known container bug (apple/container#2051) in which a network's containers can reach each other but not the Mac or the internet, and their published ports stop answering. Restart container… in the banner fixes it. Every running container stops and is not started again automatically, so start them, or their groups, afterwards. See Volumes and networks.

A container on a fresh volume stops straight away

A new named volume mounts owned by root. An image that runs as a non-root user and does not fix that itself — Redis is one — cannot write to it and exits. Use an image that handles it, or run as a user that can write there.

Logs do not follow

Switch on Live in the Logs toolbar or a container's Logs tab; otherwise each read is one bounded snapshot that updates on refresh. Live is refused above eight sources at once — narrow the Sources filter. See Logs and diagnostics.

A log or command output ends abruptly

Each stream is capped at 4 MiB per invocation. When the cap is hit the result is marked truncated — look for that marker rather than assuming the output ended naturally.

Containers report 0% CPU

Stats are sampled as deltas between polls, so the first sample after a container starts has nothing to compare against. Give it one poll interval.

Nothing happens when I double-click a row

If more than one row is selected, that is deliberate. "The one you clicked" cannot be recovered from a multi-selection, so opening an arbitrary member would sometimes open the wrong container.

The Flotilla Helper does not respond

Check System Settings ▸ General ▸ Login Items & Extensions and approve the Flotilla Helper, then look at its state in Settings ▸ Advanced. A locally built, ad-hoc-signed Flotilla cannot use the Helper at all: each side requires the other to be signed by the same Developer ID team, and an ad-hoc build has no team. See Flotilla Helper.

macOS notifications disappear too soon

Open System Settings ▸ Notifications ▸ Flotilla and choose Persistent. New installs ask for persistent alerts, but macOS reads that only once, when Flotilla first asks to notify — a Mac that already had Flotilla keeps the style it had — and lets you change it at any time. See Notifications.

The fleet

A new host does not appear

Open Flotilla on the host, check it is set to Host in Settings ▸ Hosts and Fleet, and answer macOS's local network prompt. If it was denied, turn Flotilla on in System Settings ▸ Privacy & Security ▸ Local Network and reopen the app. Neither a configuration profile nor MDM can grant this, so even a managed host needs that one click.

Bonjour finds hosts on the same network only. Otherwise choose By address in Add Host and type a name such as mini.lan or an address such as 10.0.1.20.

Reaching a host away from the office

Use a VPN or a routed subnet, and add the host by the name or address that reaches it there. A .local Bonjour name normally does not cross networks. Flotilla keeps the address you typed and uses it wherever Bonjour cannot see the host — and SSH, Screen Sharing and File Sharing use it too.

"container stopped" or "not answering"

container stopped, in amber, means the host's Flotilla answered and its container is not running. Use Start on the host's page or its row menu, if the host lets its admin start and stop container; otherwise someone at the host has to.

Not answering means the host's Flotilla did not reply. Check that Flotilla is running there, the Mac is awake and on the network, and its port (7868 by default) is reachable. A macOS notification follows after two minutes of silence, not at the first missed check.

A host will not update, or does not upgrade container

• A host installs a Flotilla update only if Install Flotilla updates from its admin is on there, and only once it is idle. Rollouts go one host at a time and stop at the first failure, so one stuck host holds up the ones after it.
• A host on a build from before wire version 6 cannot be updated from the admin. Update it by hand once.
• A host upgrades container by itself only when nothing is running, because the upgrade stops every container. With containers running it waits for you: use Upgrade…, which says how many it will stop. Both need the host's Flotilla Helper switched on.

See Updates.

Containers on two Macs cannot reach each other

They can, but only through published ports. Each Mac's networks are its own, and Flotilla does not join them. DNS names across Macs resolve, but only a published port answers. See DNS.

A Kubernetes cluster will not create

Rosetta. container 1.5's k8s create always turns Rosetta on, so a Mac without it fails. Install it on the Mac where the cluster will run — an administrator is asked:

softwareupdate --install-rosetta --agree-to-license

Then create the cluster again. On a host, creation shows no progress until it finishes, which can take several minutes; wait before deciding it failed.

kubectl cannot reach a host's cluster

Expected, for now. A cluster on a host is reached with kubectl on that host; your admin Mac cannot reach it yet, and Write Kubeconfig is for clusters on This Mac only. See Kubernetes.

Still stuck

Produce a support bundle — Help ▸ Create Support Bundle…, also in the menu-bar menu's Troubleshoot. It is redacted: home paths, credentials in URLs, keys, tokens and bare account names are removed. It shows you every file before you save it, and nothing is uploaded. Check it before sharing it anyway; that is good practice regardless of what the app promises.