03 - Workspace Errors#
Workspace errors occur when Helmor can't create, open, or operate on a workspace's filesystem or Git state. Most are recoverable with the steps below.
Common error codes#
| Error | Meaning | Fix |
|---|---|---|
| WorkspaceBroken | Workspace unusable at the filesystem or Git layer. | Check disk path, verify Git state, recreate if unrecoverable. |
| WorkspaceNotFound | Database row missing — the workspace was deleted or corrupted. | Remove the entry and create a new workspace. |
| BranchInUse | The target branch is already checked out in another worktree. | Use a different branch, or archive the conflicting workspace. |
| BranchNotFound | Branch doesn't exist locally or on the remote. | Fetch from remote (git fetch) or pick an existing branch. |
Diagnosis steps#
1. Check the workspace path#
Find the workspace directory (shown in workspace settings or logs):
ls ~/.helmor/workspaces/<repo-name>/<workspace-dir>/
git -C <path> status
If the directory is missing or Git reports a broken state, the workspace is unrecoverable — archive it and create a new one.
2. Verify the branch exists#
git -C <repo-path> branch -a | grep <branch-name>
If the branch was deleted on the remote, create a fresh workspace from an existing branch.
3. Check for worktree conflicts#
git -C <repo-path> worktree list
If another worktree already has the branch checked out, either archive that workspace or choose a different branch.
4. Inspect database state#
In rare cases, the SQLite database and filesystem can drift. Restarting Helmor re-validates workspace state on load.
Prevention#
- Archive workspaces when done — frees worktrees and reduces conflict surface.
- Don't manually modify
~/.helmor/workspaces/— let Helmor manage the filesystem. - Pull before creating — ensure your local branches are up to date.
Related#
- Debugging Guide — layer-by-layer troubleshooting.
- Create a Workspace — correct creation flow.