A container will not install or start
Recover an unavailable engine, identify image-pull and startup failures, and resolve Compose deployment errors.
Use this page when an install fails, a container stops, or a stack will not deploy. If the container stays running but its page will not open, follow A container app will not open.
Get the selected engine running
Check Settings → Containers for the selected engine. The Containers page says whether it is missing or not running; the Container engine row in Settings → Health shows the full message.
If it is missing, install it using the link in Settings → Containers. On a Mac with no
engine at all, the Containers step of the Welcome window
installs it. If installed but stopped, run container system start in Terminal on the Mac. If
Udon reports an unsupported version, update it using the linked release page. Include any
client/apiserver version mismatch from Udon's log when asking for help.
Confirm that the Containers list returns. Switching engines restarts Udon and does not move containers or volumes between engines.
Find the failing step
Read the install output before choosing Try again. For a failed pull, check the complete image reference and tag, then resolve the registry or network error shown. For a start failure, check the reported ports, mounts, command, and environment values against the app's requirements.
If the browser disconnected, check the Containers list before retrying. If the container stops again, open its Logs. Check for a missing setting, inaccessible data folder, or unavailable dependency. Review the catalog's Dependencies and Install instructions.
Recover a failed replacement
An update or reinstall pulls the image before removing the old container. A failed pull leaves the old container in place. If the error says the old container was removed and the new one could not start, fix the reported cause and recreate it from its app or saved settings, using the same data volumes.
Keep those volumes while recovering. See Deploy a container for the Run form and settings that need an admin account.
Check Compose deployment
Composer requires OrbStack. Give the stack a name and fix the validation message before Deploy. If the check itself failed, use Retry check after restoring the connection. Saving a file does not deploy it; use Deploy or Redeploy.
Host mounts and other privileged options can require an admin. If Edit in Composer reports a missing compose file, restore it to the path in the error. For a partly running stack, inspect each stopped member's logs before redeploying.
Confirm the containers stay running and their logs show startup completing. If they still fail, email [email protected] with Udon and engine versions, the image/tag, exact error, failed step, and relevant logs. Remove secrets from environment values and compose files before sending.