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:

wsm list repos --output-mode data

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

Fix:

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:

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:

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:

wsm delete <name>  # removes the stale JSON config

If wsm delete fails because it cannot find the directory, delete the JSON file manually:

rm ~/.config/workspace-manager/workspaces/<name>.json

Create succeeds but workspace looks wrong

Check the workspace JSON:

wsm info <name>
wsm info <name> --field path

If the path or repos look incorrect, delete and recreate:

wsm delete <name>
wsm create <name> --repos correct,repos

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:

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:

   wsm rebase status --repo <repo-name>
   

   📋

2. Resolve conflicts manually:

   cd <workspace-path>/<repo-name>
   # edit the conflicted files
   git add <resolved-files>
   

   📋

3. Continue the rebase:

   wsm rebase continue --repo <repo-name>
   

   📋

4. Or abort if recovery is not worth it:

   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:

  wsm rebase --manual --target main
  

  📋

Want to preview before rebasing

Use --dry-run to see what would happen:

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:

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

wsm commit -m "your message" --push

Add --add-all to also stage all unstaged changes:

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:

   wsm delete <name> --force-worktrees
   

   📋

Want to keep the files but remove the workspace registration

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:

wsm runner my-script.js

Script returns nothing

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

// 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:

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:

# 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