Troubleshooting and frequently asked questions

Symptom. The window does not open, stays blank, or the interface does not render.

Cause. The main process may fail during startup; a blank window more often points to the Chromium renderer.

Remedy. Quit Singularity completely, relaunch it, then open Help → Show Log File. If the UI is unavailable, read singularity-main.log at the path under Logs and bug reports. During development, also read the pnpm dev terminal and use View → Toggle Developer Tools.

Symptom. The card displays exactly “Failed to launch agent” or “Agent run failed”.

Cause. The provider CLI is missing, outside Electron’s PATH, or not authenticated.

Remedy. Under the same user account, run the CLI version command, then its login or status command. If it is not found, install the official CLI and fully restart Singularity to reload PATH. See AI providers.

Symptom. Exact message: “Engine is on a stale build (cannot stop a review_required run). Restart Electron (kill pnpm dev and relaunch) so the orchestration fixes load.”

Cause. The renderer and active engine do not come from the same build.

Remedy. Quit the entire application. During development, stop pnpm dev, close every other Singularity Electron instance, then relaunch.

Symptom. The tab shows “No agent work to review” or an explicit state.

Cause and remedy.

• “The agent is still working”: follow the terminal.
• “Already merged”: inspect Graph and disable automatic merge in future.
• “Direct run — no worktree”: enable worktrees and disable automatic merge.
• “The agent is waiting for an answer”: answer from the kanban card.
• “The ticket cannot be reviewed”: check its status and rerun it in an unmerged worktree.

See Review.

Symptom. An old folder remains. The targeted action states: “The worktree folder is removed. The branch and its commits are preserved.”

Cause. An interrupted, review-pending, or unintegrated run keeps its isolated checkout.

Remedy. Verify its commits, then remove only that worktree in Singularity or with git worktree remove <path>, followed by git worktree prune. Do not use global cleanup if you want to keep the branch. See Worktrees and Git hooks.

Symptom. Output stops in the hook; Singularity explains that “a non-zero exit code interrupts the Git operation”.

Cause. A test, lint, formatting, or project check failed. The commit did not happen.

Remedy. Read the first actionable error, run the hook command locally, fix it, then retry the commit. Do not pass --no-verify or disable the hook.

Symptom. Completion and diagnostics remain unavailable; the log contains “Failed to spawn” or “Runtime error”.

Cause. The module is inactive, its executable is missing, or the process exits during startup.

Remedy. Check “Enable … for IntelliSense”, install the required runtime, and read singularity-main.log. See Language servers.

Symptom. The module stays disabled or activation fails.

Cause. A required permission was not granted, or the module is incompatible with this version.

Remedy. In its details, check compatibility and grant only required permissions. Update the module or leave it disabled; do not alter its manifest to force activation.

Symptom. Startup fails in SQLite or PRAGMA integrity_check; does not return ok. “NOT NULL constraint failed: _module_migrations.timestamp” means an invalid migration, not corruption: resetting will not fix it.

Cause. singularity.db or its WAL files may be damaged.

Remedy. Quit all instances and back up the database. Delete singularity.db, singularity.db-wal, and singularity.db-shm together from ~/Library/Application Support/Singularity/ (macOS), %APPDATA%\Singularity\ (Windows), or ~/.config/Singularity/ (Linux), then relaunch.

Warning: you lose local workspaces, tickets, histories, settings, and DB Browser connections. Git repositories remain intact. Removing the whole profile also deletes caches, logs, preferences, and local secrets.

Symptom. A notification such as “Failed to launch agent” does not explain the failure by itself.

Cause. Details are in singularity-main.log, shared by the main process and renderer, rotated at 5 MB with three archives.

Remedy. Use Help → Open Logs Folder or Help → Show Log File. Paths: ~/Library/Logs/Singularity/singularity-main.log (macOS), %APPDATA%\Singularity\logs\singularity-main.log (Windows), ~/.config/Singularity/logs/singularity-main.log (Linux).

In the report, give steps, expected and observed results, version, platform, exact message, and a log excerpt around the timestamp. Remove secrets and personal paths. See Notifications.