#Troubleshooting

Start here when Sero will not launch, a workspace runtime is unavailable, or a preview does not work.

First run Environment Doctor. It checks your platform, runtime, profile, providers, plugins, and workspace state, then reports which items passed, warned, or failed.

Use this page by symptom. For exact platform support, see Support Scope. To choose or switch between Host, Apple Container, and Docker / Podman, see Choose a Workspace Runtime.

#1. Run Environment Doctor first

If Sero opens:

1. Press ⌘K on macOS or Ctrl+K elsewhere.
2. Choose Diagnostics → Environment Doctor.
3. Run the full check.
4. Select Export or Copy JSON before you change anything else.

If Sero does not open, run Doctor in safe mode from the built app or Electron command you normally use:

electron --doctor --json --report ./sero-doctor-report.json

If your install includes the bundled shim, you can also run:

sero-doctor --json --report ./sero-doctor-report.json

A failing Doctor result is usually the best next action. Fix the failed row, rerun Doctor, then retry the workflow that failed.

#Sero will not start

1. Run Environment Doctor in safe mode.
2. Check whether Doctor reports native module, profile, provider, or plugin failures.
3. If you started a development process in a terminal, stop it in the same terminal. Do not use a broad process-name kill command.
4. If you are running from a source checkout, retry the normal source-build path:

pnpm build
pnpm dev

Source-development logs are in ~/.sero-ui/logs/, unless $SERO_LOG_DIR sets another location. These compatibility links point to the current log files:

• /tmp/sero-vite.log
• /tmp/sero-electron.log
• /tmp/sero-web-remote-watch.log
• /tmp/sero-remote-<plugin>.log

If the failure mentions node-pty, better-sqlite3, ERR_DLOPEN_FAILED, or NODE_MODULE_VERSION, use the native-module steps below.

#macOS won't open Sero

Current Sero releases are signed with a Developer ID certificate and notarized by Apple, so the DMG should open normally with no Gatekeeper prompt.

If macOS warns that it "could not verify Sero is free of malware" or says Sero is damaged, you almost certainly have an older, pre-notarization build. Delete the installed app, download the latest DMG from the releases page, and reinstall.

If the latest release still fails, report the release filename and your macOS version. Do not bypass Gatekeeper or clear the quarantine attribute.

#Terminals or browser cookie import fail after install

Interrupted installs and Electron ABI changes can leave native modules in the wrong state.

From the repo root, rebuild the module named in the error:

node scripts/rebuild-node-pty.mjs
node scripts/rebuild-better-sqlite3.mjs

Use the node-pty repair when terminals fail. Use the better-sqlite3 repair when the Web plugin cannot read browser cookies.

If the repair still fails, include the command output and Doctor report in your issue.

#Container runtime is unavailable

First confirm whether the workspace is actually using a container runtime. Host is the default on supported platforms. Apple Container and Docker / Podman are explicit per-workspace choices.

If you selected a container runtime and it is unavailable, Sero reports that selected runtime as failed. It does not silently switch that selected workspace to Host. Fix the selected runtime or explicitly choose another supported runtime.

#Apple Container checks

Apple Container is for supported Apple Silicon Macs only.

/usr/local/bin/container --help
/usr/local/bin/container system status

If it is installed but stopped:

/usr/local/bin/container system start

If you are not on a supported Apple Silicon Mac, choose Host or Docker / Podman according to Support Scope. macOS Intel is not a supported Sero target.

#Docker / Podman checks

docker info
podman info

The runtime picker calls this option Docker / Podman. The saved runtime ID is docker. Sero prefers Docker when both engines are available, but can use Podman when configured or auto-selected.

If Docker Desktop, the Docker daemon, or the Podman machine/service is stopped, start it and retry Doctor.

#Host runtime tools or browser automation fail

Host runs commands directly in your real workspace folder. It is the default on supported macOS arm64, Linux x64/arm64, and Windows x64 systems.

Common Doctor results and next actions:

Host browser automation is ready only when a browser pack is available for your platform and Environment Doctor passes the launch check. Available public Host browser packs are macOS arm64, Linux x64, Linux arm64, and Windows x64. Windows arm64 is not supported today.

#A workflow works in containers but not on Host

Host and container runtimes do not provide identical behavior.

Use Host for normal local development, direct workspace paths, and loopback preview workflows. Switch the workspace to Apple Container or Docker / Podman when you need:

• container-provided tools or compiler stacks
• Linux/container parity
• container networking behavior
• browser automation from the runtime image

For the runtime decision path, see Choose a Workspace Runtime. For exact behavior, see Containers and Host Mode.

#Preview URL fails

First identify the workspace runtime.

#Host preview checks

• Start the dev server normally in the real project folder.
• Open the reported 127.0.0.1 URL in your normal browser.
• Register the server if Sero does not know about it:

sero devserver register --name "Web app" --port 3000 --command "npm run dev" --framework vite
sero devserver list

Use the URL reported by sero devserver list.

#Container preview checks

Many frameworks must bind to all interfaces inside the container:

npm run dev -- --host 0.0.0.0

Then register the same command:

sero devserver register --name "Web app" --port 3000 --command "npm run dev -- --host 0.0.0.0" --framework vite
sero devserver list

The registry is in memory. If the entry is gone after an app restart, register the server again. Always use the URL that sero devserver list reports. Do not use a container IP.

For the full dev-server guide, see Preview Dev Servers.

#Browser or app capture fails

sero browser ... commands operate on visible in-app browser tabs. sero app ... screenshot, interaction, preview, and recording commands use the UI-backed app-control bridge. Both need the target panel to be loaded and visible.

Quick checks:

sero browser list
sero app list
sero app open explorer
sero app screenshot --save ./debug.png

If screenshots say the app panel is not found or not visible, switch to the target app and retry after it renders. See Browser and Capture.

#Checkpoint restore or undo fails

Before restoring or undoing a turn:

• stop any active streaming agent turn
• confirm you are in the intended workspace and session
• review current diffs so you know what may be overwritten
• refresh Git/source-control views after restore
• distinguish VCS-only restore from Undo this turn

See Checkpoints and Undo.

#Unsupported target or unsupported expectation

Sometimes the correct fix is to change platform or runtime.

Sero does not support macOS Intel or Windows arm64. Automatic updates are limited to macOS ZIP, Linux AppImage, and Windows Setup EXE builds. Linux DEB installs require a manual update. Sero also does not promise full Host/container parity, stable internal plugin/runtime APIs, or a hardened multi-tenant security boundary.

If your workflow depends on container-provided tools, container networking, or browser automation without Host browser packs, choose Apple Container or Docker / Podman on a supported platform.

#What to include in an issue

Include the smallest reproducible signal and the support fields maintainers need:

• operating system and version
• CPU architecture
• Node and pnpm versions
• runtime mode: Host (host), Apple Container (apple-container), or Docker / Podman (docker)
• install path: packaged artifact or source build
• packaged artifact type or release tag when relevant
• source build branch and commit SHA when relevant
• exact command or workflow that failed
• Environment Doctor result or exported report
• relevant redacted log excerpts from ~/.sero-ui/logs/ or $SERO_LOG_DIR
• whether browser automation used a Host browser pack or a container runtime

Before sharing logs, redact tokens, auth headers, provider keys, private repository names when needed, and private local paths.

#See also

• Environment Doctor
• Support Scope
• Choose a Workspace Runtime
• Preview Dev Servers
• Containers and Host Mode
• Container Isolation
• Browser and Capture
• Checkpoints and Undo
• State and Folders
• Sero CLI