Udon won’t start or finish setup
Check the daemon, resolve permission prompts, and recover from an installation or update failure.
Use these checks if Udon does not open after installation, stays on a permission screen, or does not return after an update. Run Terminal commands on the Udon Mac, from the macOS account that installed it. Udon starts when that account logs in. Installation needs that account to be an administrator and signed in to the Mac's desktop, even if you start the command over SSH.
Check whether Udon is running
Open the Udon menu bar panel and turn on Enable Udon, then choose Open Udon. If the menu bar app is missing, open Terminal on the Mac and run:
udond status
udond startstart enables Udon's background jobs and brings back the menu bar app. If macOS still blocks
startup, check Udon under System Settings → General → Login Items & Extensions, then try
again. A failed start shows its error in Terminal, or in a dialog when you used the menu bar.
If the shell cannot find udond, try its installed path:
/Applications/Udon.app/Contents/MacOS/udond startThe installer finishes before the permission steps. Complete them in the Welcome to Udon window, or open Finish setup in the menu bar panel to bring it back; Udon continues setup automatically. A missing container engine or Homebrew does not block core setup.
The Add the udond command step creates /usr/local/bin/udond. If the command is still
missing, open Finish setup in the menu bar and click Add again. If Udon says it couldn't
add the command and /usr/local/bin/udond already exists, remove it with
sudo rm /usr/local/bin/udond and click Add again. If /usr/local/bin is missing from your
shell's PATH, add it in your shell configuration or use the full path above.
A not installed status means the service is not loaded in this account; it does not prove
that the files are gone. If starting fails, keep the command's error and continue below.
Resolve the permission screen
For Admin Privileges, open Finish setup in the menu bar panel and click Allow on the Allow admin privileges step, or click Permissions → Admin Privileges. Approve the macOS administrator prompt on the Mac; it is separate from Full Disk Access.
If Health says the helper is unavailable or is not running as root, use the same menu bar action to install it again. If Udon reports that it cannot find the helper, keep that error for support rather than deleting system files.
The helper serves only the macOS account that installed it. If another account on this Mac owns it, Allow fails with Udon couldn't get Admin Privileges. Sign in to the owning account and continue there. Dashboard user accounts do not change which macOS account owns the helper.
For Full Disk Access, turn on the single Udon app switch in System Settings. The daemon and menu bar app each check the grant; setup waits while either one reports a refusal. Follow Verify Full Disk Access. See Menu bar permissions for the controls.
Read the startup error
If Udon keeps stopping, read the end of its log:
tail -n 80 "$HOME/Library/Application Support/sh.udon/udond.log"Look for the first error at the time you tried to start it, including configuration, file
permission, or listening-port errors. If you recently edited config.toml, undo that edit
and run udond restart. Keep the state folder: it contains your accounts, settings, and keys.
If Udon stays running but the browser cannot connect, continue with The dashboard will not open.
Check an installation or update failure
For a failed download, signature check, or free-space check, keep the exact message. Udon checks the payload before replacing the current installation. Resolve the reported problem and retry the official install command.
If the failure happened after replacement began, follow Update recovery. It covers automatic rollback, a restart interrupted by a reboot, and Restore previous installation. Keep the state folder and any recovery files named in the error.
Confirm recovery by opening the dashboard and checking Settings → Health. Both permissions should be allowed. After an update, check the version in Settings → License → About too. Restarting Udon disconnects the dashboard and ends its terminal sessions; running containers stay with their engine.
If it still fails, email [email protected] with your Udon and macOS versions, whether this followed an install or update, the status output, and relevant log lines. Include any helper or rollback error. Remove passwords, tokens, and private details from logs.