Troubleshooting

Solutions for common issues you may encounter when using Kangentic.

Session recovery

Agent crashed mid-task

If an agent session crashes unexpectedly:

The task card shows an Exited status
Your work is safe - the git worktree and all file changes are preserved
Drag the task back to any active column to respawn the agent with the same prompt and worktree
The new agent picks up from the file state left behind

Orphaned sessions

On rare occasions, a session may show as Orphaned - this means the PTY process exited without Kangentic detecting it cleanly. Orphaned sessions are cleaned up automatically on app restart. You can also drag the task to Done and back to an active column to force a fresh session.

App crashed during active sessions

Kangentic persists session state to its database. When the app restarts after a crash:

Sessions that were running are detected and reconnected if the PTY process is still alive
Sessions whose PTY process also died are marked as exited
Worktrees and file changes are always preserved regardless of crash state

Agent CLI issues

CLI not found

Kangentic auto-detects each supported agent CLI on your PATH (claude, codex, gemini, cursor-agent for Cursor, copilot, grok, agy for Antigravity, goose, opencode, aider, qwen, kimi, droid, oz for Warp, and ollama). If the one you want isn’t detected:

Verify the CLI is installed: run its version command in your terminal (e.g. claude --version, codex --version)
If installed but not found, set the path manually in Settings > Agent > CLI path - there’s one row per detected agent
Alternatively, set agent.cliPaths.<agent> in your config file to the full path of the binary (e.g., agent.cliPaths.claude, agent.cliPaths.codex)

On macOS and Linux, Kangentic also checks a standard set of fallback install locations for thirteen of the fifteen agents (Cursor and Warp look only on PATH) - Homebrew (/opt/homebrew/bin, /usr/local/bin), Linuxbrew, ~/.npm-global/bin, ~/.local/bin, Volta, Bun, Cargo, and installed nvm versions - to handle the Finder-launch case where Electron doesn’t inherit your shell PATH. A few agents layer extra paths on top: Claude on macOS, Grok’s ~/.grok/bin on every platform including Windows, and Windows locations for Antigravity and Kimi.

Cursor is the one case with two names. It installs both cursor-agent and a short agent shim, and Kangentic looks for cursor-agent first, keeping agent only as a fallback. That ordering matters if you also have Grok Build installed, because xAI’s CLI publishes its own agent shim: on Windows that one wins PATHEXT order, so probing the short name found Grok and reported Cursor missing.

A configured path is probed and used as-is. If it does not answer its version command, the agent reports as not found at that path rather than silently resolving to a different binary on PATH, so an override pointing at a stale install shows up as the problem it is.

Since v0.39.0 detection walks every PATH match for a name in order, spending at most four version probes per agent, rather than stopping at the first hit. On Windows the lookup searches the working directory before PATH, so a gemini.cmd left in a project root by an uninstalled local package used to shadow the real global install and report the agent missing. An npm shim whose target script no longer exists is now skipped without a probe. Warp’s oz uses its own detector and still takes only the first match.

A spawn that resolves an agent whose CLI is missing no longer fails silently. The card stays where it is and a toast explains why:

Codex CLI not found on PATH. Install it, or set its path in Settings > Agent.

Authentication errors

If agents fail to start with authentication errors:

Run the agent CLI directly in your terminal and complete its authentication flow (e.g., claude, codex, gemini, aider)
Kangentic uses each CLI’s own local credentials - it doesn’t manage authentication itself for any agent

Shell issues

Wrong shell detected

Kangentic auto-detects your shell. If it picks the wrong one:

Open Settings > Terminal > Shell
Set the full path to your preferred shell

See Shell support for the detection order on each platform.

PowerShell execution policy (Windows)

If agents fail on Windows with execution policy errors, PowerShell may be blocking script execution. Run this in an elevated PowerShell:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

The policy also decides how an npm-installed agent is launched. Under RemoteSigned (or Unrestricted), Kangentic runs the agent’s .ps1 shim, which carries a multi-line task prompt intact. Under the Restricted default of Windows PowerShell 5.1, it has to fall back to the .cmd shim through cmd.exe, whose command line ends at the first newline, so the prompt is flattened to one line instead. Set the policy as above in the shell Kangentic uses, then restart the app. See npm .cmd shims under PowerShell and Git Bash.

WSL path issues

If WSL paths aren’t resolving correctly, ensure your project is on a Windows-accessible path. Kangentic converts between Windows and WSL paths automatically, but paths on WSL-only filesystems (like \\wsl$\) may cause issues.

Git worktree issues

Worktree creation fails

Common causes:

Uncommitted changes on the base branch - commit or stash changes before creating tasks
Branch name conflicts - Kangentic generates unique branch names (<slug>-<short-id>), but if a conflicting branch exists, delete it manually
Locked index - another git process may hold the lock. Check for .git/index.lock and remove it if stale
A process is holding the old worktree directory - on Windows a directory that is some process’s current directory cannot be deleted, so a dev server an earlier session left running blocks the cleanup and the next worktree on that path. Kangentic ends a session’s leftover processes when a task moves to To Do or Done or is deleted, and reaps orphaned holders when a removal fails. If the directory still cannot be reclaimed, the error names the holder: Held by node.exe (pid 12345). Close it and retry. Close that process, or the terminal or editor sitting in the folder, and retry

”Base fetch failed” on a spawning card

Every spawn freshens its base branch from origin first (since v0.37.0), so a task never quietly starts from a base you last pulled days ago. When that fetch fails, the card’s spawn-progress label picks up a (base fetch failed) note and one toast per project explains it. The agent still starts, but it starts from your last fetched state.

Usual causes are the ordinary ones: no network, or credentials your git remote needs and the app cannot supply (an expired SSH key passphrase, an unauthenticated gh). Fetch by hand in the project directory to see the real error. A repository with no origin remote stays quiet, since there is nothing to be behind.

A card says “(base N behind)”

A spawn that reuses a worktree it already has never moves that branch on its own, so the label is a measurement, not a failure. Use Update from base in the task detail window’s kebab menu when you want the branch caught up. See Starting from a fresh base.

Worktree cleanup

Worktrees are removed automatically when tasks move to Done, which reclaims the disk but keeps the branch, so the task can be moved back out and resumed. The branch goes only on a move to To Do, a delete, or a demote to the backlog, and only when git.autoCleanup is enabled (the default). To manually clean up:

Move the task to Done to drop the worktree directory and keep the branch
Or delete the task from the board, or move it to To Do, to drop both (with Auto Cleanup on)

If a worktree directory persists after cleanup, remove it manually:

git worktree remove .kangentic/worktrees/<task-number>

Worktree directories are named after the task number. Worktrees created before this scheme keep their original <slug>-<short-id> folder name, so check the directory listing if the task number does not match anything.

Performance

High memory usage

Each concurrent agent session runs a separate PTY process. If memory is constrained:

Reduce agent.maxConcurrentSessions in settings (default: 8)
Move idle tasks to Done to suspend their sessions
Close projects you’re not actively using
End the browser pages you are finished with. A loaded Browser pane costs roughly 120 MB and hiding it with the Browser pill deliberately keeps it alive for the agent, so use Close browser - in the pane’s toolbar, or in the task menu if the pane is hidden. A green dot on the Browser pill and a green globe on the task card mark the tasks still holding one

The window went blank

On Windows, Kangentic checks the machine’s commit charge once a minute and raises a standing toast (“This computer is nearly out of memory reservations…”, naming how much is left and how many agents are running) once headroom drops below 2 GB, or 5% of the commit limit on a smaller machine. It fires once per crossing rather than every minute, and it stays on screen rather than fading, because a warning about a machine running out of memory that vanishes on its own is worse than none. Since v0.43.0 it also clears itself once headroom climbs back well clear of the line, so the only standing toast you have to dismiss by hand is one describing a condition that is still true.

The wording is deliberate: commit charge counts every reservation a program makes whether or not it ever touches it, and it is bounded by RAM plus the page file. So Task Manager can show RAM half free while this fires, and the lever that raises the limit is the page file rather than more memory.

When the machine does run out, the operating system usually kills Kangentic’s window process rather than the app as a whole. Since v0.42.0 the window reloads itself when that happens, because your agents live in the main process and survive it untouched: recovery costs a repaint, never their work. If a fresh window dies too, three times inside ten minutes, Kangentic stops reloading and shows a dialog saying so, with the last memory reading it took. Your agents are still running; restart Kangentic to reconnect to them, and free some memory first, since the window will only die again on a machine with none left.

Graphics acceleration is off

Chromium draws the app through a separate graphics process. When that process fails repeatedly, or cannot be started again, and runs out of fallbacks, Chromium shuts the whole app down on purpose: no crash dialog, no warning, the window simply disappears. On some machines that happens within seconds of launching, which looks like an app that will not start. On others, so far only Linux, it happens a few minutes into a normal session.

Since v0.43.0 the next launch recovers itself. It starts without graphics acceleration, which removes the graphics process entirely and takes that shutdown off the table, raises a toast saying so, and leaves Graphics acceleration switched off under Settings > Performance with a note that Kangentic was the one who turned it off.

Until v0.43.2 that recovery covered only a graphics process that crashed. One that could not be started again reported nothing, so the next launch found no trace of it and started on the GPU again. Kangentic now records the moment Chromium falls back from GPU rendering as well, which lets the next launch recover from most of those failures too.

Only a graphics process that actually fails counts. Before v0.44.0, shutting down or restarting the computer with Kangentic open could read as a crash loop: Windows kills the graphics process and refuses to start a new one while the session ends, and the next launch turned acceleration off on a healthy GPU. Since v0.44.0 a shutdown, ending the app from Task Manager, or running out of memory no longer counts. If that happened to you on an earlier version, turn Graphics acceleration back on.

What is different while it is off:

Terminals render through the DOM path instead of WebGL, so a long burst of agent output is less smooth. Everything still works, and Kangentic stops retrying WebGL rather than probing for a context that cannot exist on this launch.
Animations and the rest of the interface are unaffected.
Nothing turns it back on by itself. Switch Graphics acceleration back on and choose Restart now when you want to try hardware rendering again: Kangentic restarts with acceleration on, and running agents resume after the restart. If the failure returns, the next launch turns it off again.

Kangentic does not claim a cause, because it cannot see one from the inside. On the installs that failed at boot, the failures started seconds in, before any agent or terminal existed. A display driver is the usual culprit for that shape, so updating yours is worth trying first. If it keeps happening, the crash records under <project>/.kangentic/logs/crashes/ (kind gpu-process-gone) are what to attach to a bug report. A record whose message ends in “(not a GPU fault)” was a kill or a shutdown, not a failure. A graphics process that could not be started at all leaves no such record, because Chromium never reports a failed start to the app. Only the fallback is recorded.

Model acceleration under Settings > Knowledge Graph is a different setting despite the similar name. It picks where the local search model runs and has nothing to do with how the app draws.

Slow terminal rendering

If terminal output is laggy:

Reduce agent.maxConcurrentSessions so fewer live terminals render at once

Data and configuration

Project folder not found

If you moved or renamed a project folder, Kangentic shows a Project Folder Not Found dialog on launch with a Locate Folder… button. Point it at the new location and everything (tasks, sessions, board history) carries over. To move a project proactively, use the Move… button under Project Settings > General and let Kangentic relocate the folder itself. See Relocating a project.

Reset project configuration

To reset a project’s settings to defaults, delete its local config:

rm <project>/.kangentic/config.json

The project will use global settings on next launch.

kangentic.json needs fixing

A banner saying kangentic.json cannot be read usually means a git merge or git pull left conflict markers in it. Since v0.44.0 Kangentic never overwrites such a file: the board loads from its own database, and profile, shortcut, and base-branch saves are refused until the file is valid JSON again. Resolve the conflict and save; the fixed file applies over anything you changed meanwhile. See Board configuration.

Database issues

Kangentic uses SQLite for data storage. If the database becomes corrupted:

Close Kangentic
Delete the database file from the data directory
Relaunch - a fresh database is created automatically

”Kangentic can’t read its database”

A global database Kangentic cannot open is reported rather than crashing the launch (since v0.39.0). The dialog names the file path and the SQLite error code, lists the usual causes (another program holding the file: an antivirus scan, a OneDrive or Dropbox sync, or a failing drive), and offers Retry and Quit. A lock is usually over within seconds, so Retry reopens the database without a relaunch. The same dialog can appear once while the app is running if the project list stops being readable; project reads come back empty until a Retry succeeds, and a successful Retry re-arms the dialog for a later outage.

Semantic search falls back to keyword

Conversation memory runs its embedding model in a separate background process. If that process crashes three times inside five minutes, Kangentic stops restarting it and search stays on keyword matches until the window clears. Searching keeps working throughout, which is why this can go unnoticed, and the Knowledge Graph loses search by meaning until it recovers.

The Knowledge Graph card in Settings > Knowledge Graph names the reason when it happens. Its note reads “The local model is unavailable - showing keyword matches.” with how the worker stopped and the first line of its error output, for example exited with code 1: Error: Cannot find module 'onnxruntime-common', or failed to start when the process could not be created at all. The same reason is written to <project>/.kangentic/logs/<YYYY-MM-DD>.log as a [utility-process] warning ending in the crash count, such as (crash 3 of 3), so it is on disk whether or not error reporting is enabled. A worker that never came up, or stopped answering, says what it failed to do instead, as in did not start in time.

Kangentic disappears on Windows (v0.39.1 only)

On Windows, installed v0.39.1 builds close instantly and without a dialog the first time Kangentic starts one of its background workers. There is no crash report and no error in the log, because the whole app is gone before either can be written.

Two things start those workers, so the moment it happens depends on what you were doing: Conversation memory indexing a project, and a diff that has a large batch of untracked files to measure. Indexing is the common one, which is why this usually looks like “it dies a few seconds after I open a project”.

Only v0.39.1 is affected, and only installed builds. Running from source is not, since a terminal gives the app the console handle whose absence causes the failure. v0.40.0 fixes it. If you are on v0.39.1, update; if the app closes before you can, reinstall from the latest release.

Finding log files

Logs are written per project, not to a platform-standard app directory, so they sit beside the code they describe:

What	Where
Console log	`<projectRoot>/.kangentic/logs/<YYYY-MM-DD>.log` (one NDJSON line per entry)
Console log, no project open	`<configDir>/logs/<YYYY-MM-DD>.log`, where `<configDir>` is the config directory
Crash reports	`<projectRoot>/.kangentic/logs/crashes/<timestamp>.json` (one file per crash), or the config directory’s `logs/crashes/` for a crash with no project open
IPC trace	`<projectRoot>/.kangentic/logs/ipc-<date>.jsonl`

Verbosity is a setting rather than an environment variable. error and warn entries are always persisted; info, debug, and log are written only when developer.persistConsoleLogs is on (see the Configuration reference). Logging is deliberately best-effort: if the write fails, entries are dropped rather than risking a crash in a diagnostic path. Since v0.42.0 a gap with no project open no longer loses entries, so a global subsystem such as the mobile bridge keeps its trace in the config directory’s log across it.

Agents can read all of this without leaving the board, through the kangentic_tail_logs and kangentic_get_recent_crashes MCP tools; kangentic_tail_logs merges the project log with the config-directory one.

Still stuck?

If none of the above resolved it:

Open a GitHub issue for a bug or crash. Include your OS, the Kangentic version, the agent CLI involved, and the relevant lines from the debug log above. Public issues get the fastest fix because other users can add detail.
Start a GitHub Discussion for a question about how something is meant to work.
Email support@kangentic.com if the problem involves logs or project details you would rather not post publicly, or if you have not gotten a response on an issue.

Please scrub file paths, task content, and anything else sensitive from logs before sharing them.