---
title: WSM Troubleshooting Guide
description: Diagnose common workspace, git, and runner issues quickly.
doc_version: 1
last_updated: 2026-08-20
---


When a WSM command fails or produces unexpected output, the cause almost always
falls into one of four categories: registry problems, workspace state issues,
git conflicts, or command context errors. This guide helps you identify which
category you are in and recover quickly.

## Quick triage

Before diving into specific errors, run through this checklist:

1. **Where am I?** Run `pwd` and confirm you are inside a workspace directory
   (or pass `--workspace <name>` explicitly).
2. **Is the registry current?** Run `wsm list repos` -- does it include the
   repositories you expect?
3. **Does the workspace exist?** Run `wsm list workspaces` -- is your workspace
   listed?
4. **What does status say?** Run `wsm status --workspace <name> --output-mode both`
   for the fullest picture.

## Registry issues

### "repositories not found" during create

The repositories you specified with `--repos` are not in WSM's registry.

**Diagnose**:
```bash
wsm list repos --output-mode data
```

Look for the missing repository names. If they are absent:

**Fix**:
```bash
wsm discover ~/code  # point at the parent directory containing your repos
wsm list repos       # confirm they appear now
wsm create my-feature --repos the-missing-repo
```

### Registry seems stale after moving repositories

WSM's registry stores absolute paths. If you move a repository to a different
directory, the old path in the registry becomes invalid.

**Fix**: Re-run discovery. It overwrites the registry with fresh data:
```bash
wsm discover ~/new-location
```

## Workspace issues

### "not in a workspace directory"

WSM cannot detect which workspace you mean. This happens when:
- You are outside any known workspace directory.
- Your working directory is not a subdirectory of a workspace path.

**Fix**: Pass the workspace explicitly:
```bash
wsm status my-feature
# or
wsm status --workspace my-feature
```

### Workspace in list but directory is gone

Someone (or you) deleted the workspace directory manually, but the JSON config
file at `~/.config/workspace-manager/workspaces/<name>.json` still exists.

**Fix**:
```bash
wsm delete <name>  # removes the stale JSON config
```

If `wsm delete` fails because it cannot find the directory, delete the JSON file
manually:
```bash
rm ~/.config/workspace-manager/workspaces/<name>.json
```

### Create succeeds but workspace looks wrong

Check the workspace JSON:
```bash
wsm info <name>
wsm info <name> --field path
```

If the path or repos look incorrect, delete and recreate:
```bash
wsm delete <name>
wsm create <name> --repos correct,repos
```

## Status issues

`wsm status` compares each repo against a resolved base branch and reports
`is_merged`/`needs_rebase`. The `BASE` column shows the resolved ref and
source; `MERGED`/`REBASE` use honest glyphs.

### `wsm status` shows `?` in MERGED/REBASE

The base branch could not be resolved into a concrete ref -- it exists neither
as a remote-tracking branch (`<remote>/<base>`) nor as a local branch. The
`BASE` column prints `? <reason>` naming the missing refs.

Fix it by setting an explicit base for that repo:

```bash
wsm set-base <repo> --branch <branch> [--remote <remote>] [--fetch]
```

Use `--fetch` so the remote-tracking ref exists before the next status check.
The override is stored in the in-workspace `.wsm/wsm.json` by default; pass
`--global` to store it in the config-dir workspace JSON (the in-workspace
override wins at load time).

### `wsm status` shows `!` in MERGED/REBASE

git itself failed while running the comparison (e.g. a corrupt object database).
The `BASE` column and the JSON `base_reason` field carry the captured stderr.
Inspect the reason; it is a git-level problem, not a WSM configuration issue.

### `wsm status` compares against the wrong branch for one repo

The base is resolved by precedence (in-workspace override > config-dir
override > workspace base > discovered default > env > `main`). A repo whose
remote default is `develop` (not `main`) should be compared against `develop`
after `wsm discover`; if it is not, either the discovered default is stale
(re-run `wsm discover`) or an override is taking precedence -- check
`.wsm/wsm.json` and `wsm set-base --global`.

### Forked workspace reports a confident false that looks wrong

This was the original bug: a forked workspace whose base branch was never
pushed had no `origin/<base>` ref, so the old checks swallowed an `exit 128`
into `false`. The fix resolves the local base branch as a fallback; the `BASE`
column now shows `task/<base> (local)` and `MERGED`/`REBASE` reflect a real
comparison.

## Rebase issues

Rebase is the most complex multi-repo operation. Problems usually affect one
repository at a time.

### Rebase fails for a single repo

The other repositories may have rebased successfully. Check per-repo state:

```bash
wsm rebase status
```

This shows a table with columns: REPOSITORY, STATE, CONFLICTS, ERROR. Possible
states:
- `none` -- no rebase in progress
- `in_progress` -- rebase is paused (usually due to conflicts)

### Recovering from rebase conflicts

Step-by-step recovery:

1. **Identify conflicts**:
   ```bash
   wsm rebase status --repo <repo-name>
   ```

2. **Resolve conflicts manually**:
   ```bash
   cd <workspace-path>/<repo-name>
   # edit the conflicted files
   git add <resolved-files>
   ```

3. **Continue the rebase**:
   ```bash
   wsm rebase continue --repo <repo-name>
   ```

4. **Or abort if recovery is not worth it**:
   ```bash
   wsm rebase abort --repo <repo-name>
   ```

### Rebase hangs or seems stuck

If a rebase operation appears to hang, it may be waiting for an editor (for
interactive rebase) or processing a large repository.

- If you used `--interactive`, WSM opens an editor. Complete the editor session.
- Try running with `--manual` to see the exact git commands, then run them yourself:
  ```bash
  wsm rebase --manual --target main
  ```

### Want to preview before rebasing

Use `--dry-run` to see what would happen:
```bash
wsm rebase --dry-run
```

## Commit issues

### "commit message is required"

You ran `wsm commit` without `-m` and without `--interactive`.

**Fix**: Either provide a message or use interactive mode:
```bash
wsm commit -m "your message"
# or
wsm commit --interactive
```

### "No changes found in workspace"

All repositories are clean. Run `wsm status` to confirm, or `wsm diff` to check
for changes.

### Want to commit and push in one step

```bash
wsm commit -m "your message" --push
```

Add `--add-all` to also stage all unstaged changes:
```bash
wsm commit -m "your message" --add-all --push
```

## Delete issues

### Delete fails due to worktree safety checks

WSM refuses to remove worktrees that have uncommitted changes. This is
intentional -- it prevents data loss.

**Options**:
1. Commit or stash changes first, then delete.
2. If you are sure the changes can be discarded:
   ```bash
   wsm delete <name> --force-worktrees
   ```

### Want to keep the files but remove the workspace registration

```bash
wsm delete <name>
```

Without `--remove-files`, WSM removes the workspace config and worktree
registrations but leaves the directory intact.

## JS runner issues

### "Cannot find module 'wsm'"

The script was not executed through `wsm runner`. The `wsm` module is only
available inside the runner's goja environment.

**Fix**: Use `wsm runner`, not `node`:
```bash
wsm runner my-script.js
```

### Script returns nothing

The script needs to end with an expression (not a statement). Return an object
literal:

```javascript
// Wrong -- ends with a function call (statement)
console.log(result);

// Right -- ends with an expression
({
  count: repos.length,
  version: wsm.version,
});
```

### Script output is messy in automation

Use `--output-mode data` and `--print-result=false` for clean machine-readable
output:
```bash
wsm runner script.js --output-mode data --print-result=false
```

### `TypeError` from JS API call

The JS wrappers validate required inputs before running workflows. Common
examples:

- `createWorkspace` requires `name` and `repos`
- `workspaces.add` requires `workspaceName` and `repoName`
- `workspaces.merge` requires `workspaceName`
- `git.commit` requires `message` or `template`
- `git.branch.create/switch` require `branchName`

**Fix**: pass all required fields in the method input object.

### Script fails on one repository in batch operations

Some APIs return per-repository row results instead of throwing for every row
failure. Check row payloads for repository-level `success`/`error` fields:

- `git.branch.create/switch` return `results[]`
- `git.rebase.status/continue/abort` return `rows[]`

If the call itself fails (for example workspace not found), a top-level error
is thrown.

## Diagnostic commands reference

Here are the most useful commands for debugging, all using `--output-mode data`
for structured output:

```bash
# What repos does WSM know about?
wsm list repos --output-mode data

# What workspaces exist?
wsm list workspaces --output-mode data

# Detailed status for a workspace
wsm status --workspace <name> --output-mode data

# Rebase state for all repos
wsm rebase status --output-mode data

# Workspace metadata
wsm info <name> --output-mode data

# Diff across workspace
wsm diff --output-mode data

# Run the smoke test
wsm runner demo/js/wsm-api-smoke.js --output-mode both
```

## Getting help

- Run `wsm --help` for the top-level command list.
- Run `wsm <command> --help` for flags and usage of any specific command.
- Check `wsm help wsm-persistence-and-state` if you suspect state corruption.
- Check `wsm help wsm-architecture-overview` if contributing or debugging
  internals.

## See Also

- `wsm help wsm-getting-started`
- `wsm help wsm-command-reference`
- `wsm help wsm-persistence-and-state`