Troubleshooting

Troubleshooting

The app shows a gate screen instead of my containers

container's background services aren't running. Click Start. The first start downloads a Linux kernel and can take a few minutes.

If it says the version is too old, the minimum is 1.2.0 — use Update… to install a current one.

Published ports don't work on macOS 27

A connection to localhost:<port> is accepted and then immediately reset, while the container's own address works fine.

This is apple/container issue #2029 — upstream, in the macOS 27 beta, and not worked around by this app. Use the container's address (shown in its detail pane) until it's fixed.

A stack's web tier can't reach its database after a restart

Starting the stack from the Stacks section should fix this by itself: services come up in dependency order and any with stale addresses are re-created with current ones.

If it persists:

• Did you start the service on its own rather than the stack? A service started individually isn't reconciled. Stop it and start the stack.
• Does the service record an address about itself somewhere — a site URL written into a database during setup? That isn't ours to rewrite. Point it at localhost:<published port>, which survives restarts.

See how services find each other.

A service in my stack is missing

The stack's detail pane says so and offers Re-create, which rebuilds it from the settings it was created with.

If there's no such offer, the service isn't in the stack's saved definition — which is the case for anything added later with Add Service… or created with the Stack picker.

Deleting an image freed no space

Stopped containers still count as references. An image badged Unused is one that no container and no machine references at all; if something still references it, its layers stay. Delete the container too, then the image.

I can't move an existing container into a stack

You can't — the runtime assigns labels when a container is created and offers no way to change them afterwards. Re-create it with the Stack picker on the create sheet, then delete the old one.

Volumes are the exception: right-click one and use Set Label…, which the app records itself rather than on the volume.

my-app.test doesn't resolve

Check Settings ▸ Local DNS. The likely states:

• Half configured — a domain exists but nothing registers under it. This is what following Apple's tutorial leaves you with. Set Up… completes it.
• Active, but this container has no name. Names are assigned at creation, so a container that existed before you set it up needs re-creating.

If a name resolves but you can't connect, check that both containers are on the same network — names resolve globally, routing doesn't. See Local DNS.

Opening a shell in Terminal.app does nothing

macOS asks for permission to control Terminal the first time, and if it was declined the app falls back to a .command file. To grant it: System Settings ▸ Privacy & Security ▸ Automation ▸ ContainerManager.

The Terminal tab inside the app needs no permission and always works.

A machine won't boot

Almost always a missing init system — the image needs one at /sbin/init. alpine has one; plain ubuntu and debian don't. Check the machine's Logs, and see building a machine image.

A build is stuck

Stop on the Build Image sheet interrupts it, and closing the sheet stops it too.

If the build itself is failing rather than hanging, the output is in the log — select it and copy it out.

Something failed and I want to see why

• Stacks — the Log button in a stack's detail pane records how it was built and anything an import couldn't carry over.
• Containers and machines — the Logs view.
• Services — start-up output appears on the gate screen while starting.

Logs can be selected and copied in one go, which is what you want when filing an issue.

Reporting a bug

Open an issue with the app version (Settings ▸ Updates), your container version, and your macOS version.

If the problem is with containers themselves rather than the app — networking, images failing to run, ports — check whether the same thing happens with the container CLI. If it does, it belongs upstream.