Troubleshooting

This guide covers common issues you might encounter with Better PM and how to resolve them.

Installation Issues

Command not found: pm

Symptoms:

pm i
# zsh: command not found: pm

Cause: Better PM is not installed or not in your PATH.Solution:

Install via Homebrew (recommended)

brew install fdarian/tap/better-pm

Or install via npm

npm install -g better-pm

Note: Homebrew is recommended as it installs a native binary with faster shell completions (~60ms vs 200-500ms).

Verify installation

which pm
# Should output: /usr/local/bin/pm (or similar)

pm --version
# Should output version number

npm global install doesn't work

Symptoms:

npm install -g better-pm
# Completes, but pm command still not found

Cause: npm global binaries directory is not in your PATH.Solution:

Find npm global bin directory

npm bin -g
# Example output: /usr/local/lib/node_modules/.bin

Add to PATH

Add this to your ~/.zshrc or ~/.bashrc:

export PATH="$(npm bin -g):$PATH"

Reload shell

source ~/.zshrc  # or ~/.bashrc

Package Manager Detection

No lock file found. Could not detect package manager

Symptoms:

pm i
# Error: No lock file found. Could not detect package manager (pnpm, bun, or npm).

Cause: Better PM searches upward from your current directory for lockfiles but can’t find one. The search stops at your home directory or filesystem root.Diagnosis:Check if you have a lockfile in your project:

ls -la | grep -E "(pnpm-lock.yaml|bun.lock|package-lock.json)"

Solutions:

No lockfile exists
Wrong directory
Lockfile above home directory

Generate one by running your package manager’s install command:

# For pnpm:
pnpm install

# For bun:
bun install

# For npm:
npm install

This creates the lockfile, after which Better PM will work.

Navigate to your project root:

# Check where you are:
pwd

# Navigate to project root:
cd /path/to/my-project

# Verify lockfile exists:
ls pnpm-lock.yaml  # or bun.lock, package-lock.json

Better PM’s findUpward utility stops at your home directory to prevent searching the entire filesystem.From src/project/find-upward.ts:20-22:

if (currentDir === homeDir) {
  return yield* Effect.fail(new Error(`${filename} not found`));
}

Solution: Move your project under your home directory, or cd into the project before running pm.

Wrong package manager detected

Symptoms:

pm i
# Running pnpm install
# (but you expected bun install)

Cause: Multiple lockfiles exist in your project, and Better PM picks the first one it finds.Diagnosis:Check for multiple lockfiles:

ls -la | grep -E "(pnpm-lock.yaml|bun.lock|package-lock.json)"

Detection order (from src/pm/detect.ts:10-18):

pnpm-lock.yaml → pnpm
bun.lock → bun
bun.lockb → bun
package-lock.json → npm

Solution:Remove the unwanted lockfiles:

# If you want to use bun, remove pnpm/npm locks:
rm pnpm-lock.yaml package-lock.json

# Then regenerate:
bun install

Workspace Detection

Workspace packages not detected

Symptoms:

pm pls
# (no output, or error)

pm cd @myapp/web
# Error: Package "@myapp/web" not found

Cause: Workspace configuration is missing or malformed.Diagnosis:

pnpm
bun
npm

Check for pnpm-workspace.yaml:

cat pnpm-workspace.yaml

Should contain:

packages:
  - 'apps/*'
  - 'packages/*'

Common issues:

File doesn’t exist: Create it with your package globs
Incorrect indentation: YAML is whitespace-sensitive
Missing quotes: Use quotes for globs with wildcards

Check package.json in your root:

cat package.json | grep -A 5 workspaces

Should contain:

{
  "workspaces": ["apps/*", "packages/*"]
}

Or:

{
  "workspaces": {
    "packages": ["apps/*", "packages/*"]
  }
}

Common issues:

Missing workspaces field
Incorrect glob patterns
JSON syntax errors

Check package.json (same as bun):

cat package.json | grep -A 5 workspaces

Should contain:

{
  "workspaces": ["apps/*", "packages/*"]
}

Solution:Add or fix workspace configuration, then test:

pm pls  # Should now list packages

Some packages missing from pm pls

Symptoms:

pm pls
# Shows packages/ui but not packages/utils

Cause: Package doesn’t match workspace glob patterns, or lacks a package.json.Diagnosis:

Check package.json exists

ls packages/utils/package.json
# Should exist

Check package has a name field

cat packages/utils/package.json | grep name
# Should output: "name": "@myapp/utils"

Better PM requires a name field (from src/commands/install.ts:23-24):

const PackageJson = Schema.Struct({
  name: Schema.String,
});

Verify glob pattern matches

If using packages/ui and packages/utils:

pnpm-workspace.yaml

packages:
  - 'packages/*'  # Should match both

Test the glob:

ls -d packages/*/
# Should show both packages/ui/ and packages/utils/

Shell Integration

pm cd doesn't change directory

Symptoms:

pm cd @myapp/web
# Prints: /path/to/apps/web
# (but doesn't actually cd there)

Cause: Shell integration not activated.Solution:

Add activation to shell config

eval "$(pm activate zsh)"

eval "$(pm activate bash)"

Reload shell

source ~/.zshrc  # or ~/.bashrc

Verify wrapper is loaded

type pm
# Should output: pm is a shell function
# NOT: pm is /usr/local/bin/pm

See Shell Integration guide for details.

Tab completion doesn't show packages

Symptoms:

pm cd <TAB>
# No completions appear

Diagnosis:

Test completions directly

pm cd --completions
# Should list all workspace package names

If this works, the issue is with shell completion setup.

Check shell integration

grep "pm activate" ~/.zshrc  # or ~/.bashrc
# Should find the eval line

For zsh: check compinit order

In ~/.zshrc, ensure compinit runs after the activation:

# ❌ Wrong order:
compinit
eval "$(pm activate zsh)"

# ✅ Correct order:
eval "$(pm activate zsh)"
compinit

Or use Oh My Zsh (which calls compinit automatically).

Slow tab completions

Symptoms: Typing pm cd <TAB> takes 2-3 seconds to show completions.Cause: Using npm installation instead of Homebrew.Explanation:From the README:

Homebrew is recommended — it installs a native binary, so shell completions resolve in ~60ms.

npm installation runs the CLI through Node.js, which is slower (200-500ms startup time).Solution:Switch to Homebrew installation:

npm uninstall -g better-pm
brew install fdarian/tap/better-pm

Then reload shell and test:

source ~/.zshrc
pm cd <TAB>  # Should be much faster

Command Execution

pm i installs all packages at root

Symptoms:

cd ~/my-monorepo
pm i
# Installs everything without warning

Expected behavior: Should show a warning and prompt for confirmation.Cause: Using -y / --sure flag, or running in non-interactive environment.Diagnosis:Check your command:

pm i -y         # Bypasses prompt
pm i --sure     # Bypasses prompt
pm i            # Should prompt

Check environment:

echo $CLAUDECODE
# If "1", interactive prompts are disabled

Solution:

To install specific packages: pm i -F @myapp/web
To install everything intentionally: pm i -y
For safety, always cd into a package before running pm i

pm add with pasted command fails

Symptoms:

pm add "npm install react"
# Error: ...

Common issues:

No packages extracted
Unsupported package manager
Version specifiers

pm add "npm install"
# Error: No packages specified in pasted command. To install dependencies, use: pm i

Cause: Pasted command has no package names.Solution: Include the package name:

pm add "npm install react"

pm add "yarn add react"
# (Doesn't parse, tries to install package named "yarn")

Cause: yarn is not in the supported list (PM_NAMES = ['npm', 'pnpm', 'bun']).Solution: Extract package name manually:

pm add react

pm add "npm install [email protected]"
# May fail depending on package manager

Cause: The @18.2.0 becomes part of the extracted package name.Solution: Use explicit version:

pm add [email protected]

Package not found error

Symptoms:

pm cd @myapp/web
# Error: Package "@myapp/web" not found. Available packages: ...

Cause: Package name doesn’t match any workspace package.Diagnosis:

List all packages

pm pls

Check exact package names.

Check for typos

Package names are case-sensitive and must match exactly:

pm cd @myapp/Web   # ❌ Wrong case
pm cd @myapp/web   # ✅ Correct

Check package.json name field

cat apps/web/package.json | grep '"name"'
# Output: "name": "@myapp/web"

Use the exact name from package.json.

Performance Issues

Slow command execution

Symptoms: Commands take 2-5 seconds to start.Diagnosis:

Check installation method

which pm
# Homebrew: /usr/local/bin/pm (fast)
# npm: /usr/local/lib/node_modules/.bin/pm (slower)

Benchmark startup time

time pm --version
# Homebrew: ~0.06s
# npm: ~0.2-0.5s

Solution: Use Homebrew installation for better performance:

brew install fdarian/tap/better-pm

Large monorepo operations are slow

Symptoms: pm pls or pm cd takes several seconds in a monorepo with 100+ packages.Cause: Better PM enumerates all workspace packages by:

Reading workspace globs from config
Expanding globs to find all matching directories
Reading each package.json to extract the name

Mitigation:

Use Homebrew installation (native binary is faster)
Cache isn’t implemented yet, so each command re-scans
Consider organizing workspace into fewer, larger packages

Note: This is a known limitation for very large monorepos.

Error Messages

Common Error Reference

Error: No lock file found. Could not detect package manager (pnpm, bun, or npm).

Error: Package "@myapp/web" not found. Available packages:
  ├── apps/
  │   └── api "@myapp/api"
  └── packages/
      └── ui "@myapp/ui"

Error: No packages specified in pasted command. To install dependencies, use: pm i

Source reference: Error classes are defined in src/lib/errors.ts.

Getting Help

If you encounter an issue not covered here:

Check source code

Better PM is open source. You can inspect the implementation:

Package manager detection: src/pm/detect.ts
Install logic: src/commands/install.ts
Workspace parsing: src/pm/{pnpm,bun,npm}.ts
Shell integration: src/commands/activate.ts

Enable debug output

Run with verbose logging (if supported by Effect framework):

LOG_LEVEL=debug pm i

Report an issue

Open an issue on the GitHub repository with:

Your package manager and version
Better PM version (pm --version)
Full command and error output
Relevant workspace configuration (pnpm-workspace.yaml or package.json)

Prevention Tips

Use Homebrew

Install via Homebrew for best performance and fewer issues:

brew install fdarian/tap/better-pm

Activate Shell Integration

Add to your shell config for full functionality:

eval "$(pm activate zsh)"

Keep Workspace Config Valid

Ensure your workspace configuration is correct:

pnpm: Valid pnpm-workspace.yaml
bun/npm: Valid workspaces in package.json

Use pm pls to Verify

Regularly check that Better PM detects your packages:

pm pls

Get Started

Core Concepts

Commands

Guides

Installation Issues

Package Manager Detection

Workspace Detection

Shell Integration

Command Execution

Performance Issues

Error Messages

Common Error Reference

Getting Help

Prevention Tips

Use Homebrew

Activate Shell Integration

Keep Workspace Config Valid

Use pm pls to Verify

​Installation Issues

​Package Manager Detection

​Workspace Detection

​Shell Integration

​Command Execution

​Performance Issues

​Error Messages

​Common Error Reference

​Getting Help

​Prevention Tips

Use Homebrew

Activate Shell Integration

Keep Workspace Config Valid

Use pm pls to Verify

Installation Issues

Package Manager Detection

Workspace Detection

Shell Integration

Command Execution

Performance Issues

Error Messages

Common Error Reference

Getting Help

Prevention Tips