Troubleshooting guide

Common issues and actionable solutions organized by workflow stage.

Quick error lookup

Jump directly to your issue:

Installation:

Node version mismatch
pnpm not found

Initialization:

Already initialized
No agents detected
Permission denied

Sync:

See Sync issues

CI/CD:

See CI validation

Overlays:

See Overlay issues

Platform-specific:

Windows: See Windows platform limitations

Remote & Git:

See Source and remote issues

Still stuck? See Getting more help

Installation issues

Node version mismatch

Error:


error @aligntrue/cli@0.1.0: The engine "node" is incompatible with this module.
Expected version ">=20.0.0". Got "18.16.0"

Cause: AlignTrue requires Node.js 20 or later.

Fix:


# Check your Node version
node --version
 
# Upgrade Node.js
# Using nvm (recommended)
nvm install 20
nvm use 20
 
# Or download from nodejs.org
# https://nodejs.org/

pnpm not found

Error:


bash: pnpm: command not found

Cause: pnpm is not installed globally.

Fix:

npm

bash npm install -g pnpm

yarn

bash yarn global add pnpm

bun

bash bun install -g pnpm

Verify installation:


pnpm --version

Alternative: Run once without installing:


npx pnpm --version
npx aligntrue init

Init issues

Already initialized

Error:


⚠ This project is already initialized.

Found .aligntrue/config.yaml with mode: team

Causes and fixes:

1. Solo mode - want to re-initialize:


# Back up existing config
mv .aligntrue/config.yaml .aligntrue/config.yaml.bak
 
# Re-run init
aligntrue init
 
# Restore custom settings from backup if needed

2. Team mode - want to join existing team project:


# Don't run init! You're joining an existing team.
# Instead:
git pull  # Get latest rules and lockfile
aligntrue sync  # Generate agent files for your machine

3. Want to switch from solo to team mode:


aligntrue team enable

No agents detected

Output:


◇ Detected 0 AI coding agents.
│
◆ Choose agents to enable: (Use arrow keys)

Cause: AlignTrue looks for common agent markers (.cursor/, AGENTS.md, etc.) and didn’t find any.

Fix: Manually select agents you want to use:

During init, choose from the multiselect list (options vary by version)
Or edit .aligntrue/config.yaml after init:


exporters:
  - cursor
  - agents
  - windsurf
  # Add more as needed

Verify available agents:


aligntrue exporters list

Permission denied creating files

Error:


Error: EACCES: permission denied, open '.aligntrue/config.yaml'

Cause: Insufficient permissions to write to project directory.

Fix:


# Check directory ownership
ls -la .
 
# Fix ownership (Unix/macOS)
sudo chown -R $USER:$USER .
 
# Or run with appropriate permissions
sudo aligntrue init  # Not recommended

Better approach: Run AlignTrue as your regular user in directories you own.

Getting more help

Enable verbose logging


# Set debug environment variable
DEBUG=aligntrue:* aligntrue sync

Check versions


# CLI version
aligntrue --version
 
# Node version
node --version
 
# Package versions
cat package.json | grep aligntrue

Common troubleshooting commands


# Validate everything
aligntrue check
 
# Preview sync without writing
aligntrue sync --dry-run
 
# Show configured/available exporters
aligntrue exporters list
cat .aligntrue/config.yaml | grep exporters -A 5

Still stuck?

Check Sync issues for sync-related problems
Check CI validation for CI pipeline issues
Check Overlay issues for customization problems
Check Source and remote issues for git/SSH issues
Review Command Reference for detailed flag documentation
Open an issue at github.com/AlignTrue/aligntrue

Include in your issue:

AlignTrue version (aligntrue --version)
Node version (node --version)
Operating system
Full error message
Steps to reproduce