Troubleshooting

Common issues and solutions to help you resolve problems with PCU. Find answers to frequently encountered errors and debugging tips.

Common Errors

Workspace Not Found

Error Message:

Error: No pnpm workspace found in the current directory

Cause: PCU couldn't locate a pnpm-workspace.yaml file or detect a valid pnpm workspace structure.

Solutions:

# Create a new pnpm workspace
pcu init

# Or manually create pnpm-workspace.yaml
echo "packages:
  - 'packages/*'" > pnpm-workspace.yaml

No Catalog Dependencies

Error Message:

No catalog dependencies found in workspace

Cause: Your workspace doesn't use pnpm catalog dependencies.

Solutions:

packages:
  - 'packages/*'

catalog:
  react: ^18.2.0
  typescript: ^5.0.0
  lodash: ^4.17.21

Registry Access Issues

Error Message:

Error: getaddrinfo ENOTFOUND registry.npmjs.org

Cause: Network connectivity issues or registry access problems.

Solutions:

# Check network connectivity
ping registry.npmjs.org

# Test with increased timeout
pcu -c --timeout 60000

# Reduce concurrent requests
pcu -c --concurrency 2

Authentication Errors

Error Message:

Error: 401 Unauthorized - authentication required

Cause: Missing or invalid authentication tokens for private registries.

Solutions:

@myorg:registry=https://npm.private-registry.com/
//npm.private-registry.com/:_authToken=${NPM_TOKEN}

# Or use legacy auth
//npm.private-registry.com/:username=myuser
//npm.private-registry.com/:_password=base64password
//npm.private-registry.com/:email=my.email@example.com

Configuration File Errors

Error Message:

Error: Invalid configuration in .pcurc.json

Cause: Malformed JSON or invalid configuration options.

Solutions:

# Check JSON syntax
node -e "console.log(JSON.parse(require('fs').readFileSync('.pcurc.json', 'utf8')))"

# Regenerate configuration
mv .pcurc.json .pcurc.json.backup
pcu init --force

Debugging

Enable Verbose Logging

# Enable verbose logging
pcu -c --verbose

# Debug mode with environment variable
DEBUG=pcu:* pcu -c

# Specific debug modules
DEBUG=pcu:core,pcu:registry pcu -c

Workspace Validation

# Check workspace configuration
pcu -s --validate

# Get detailed workspace info
pcu -s --stats --verbose

Performance Issues

Slow Network Requests

Symptoms: PCU takes a long time to check for updates

Solutions:

{
  "advanced": {
    "concurrency": 3,
    "timeout": 30000,
    "retries": 2,
    "cacheValidityMinutes": 120
  }
}

High Memory Usage

Symptoms: PCU consumes excessive memory with large workspaces

Solutions:

{
  "advanced": {
    "concurrency": 2,
    "batchSize": 10
  }
}

Environment Issues

Node.js Version Compatibility

Error Message:

Error: Unsupported Node.js version

Solutions:

node --version  # Should be >= 18.0.0

# Install compatible version
nvm install 20
nvm use 20

pnpm Version Issues

Error Message:

Error: pnpm command not found

Solutions:

# Install latest pnpm
npm install -g pnpm@latest

# Verify installation
pnpm --version  # Should be >= 8.0.0

Windows-Specific Issues

Path Separator Issues

Error Message:

Error: Cannot resolve workspace path

Solutions:

# Use forward slashes in paths
pcu -c --workspace ./my/workspace

# Or use PowerShell
pwsh -c "pcu -c"

Permission Errors

Error Message:

Error: EPERM: operation not permitted

Solutions:

# Run Command Prompt as Administrator
runas /user:Administrator cmd

# Or use PowerShell as Administrator
Start-Process powershell -Verb RunAs

Getting Help

Diagnostic Information

When reporting issues, include this diagnostic information:

# PCU version
pcu --version

# Node.js and pnpm versions
node --version
pnpm --version

# Operating system
uname -a  # Linux/macOS
systeminfo  # Windows

Support Channels

  • 🐛 Bug Reports: GitHub Issues
  • 💬 Questions: GitHub Discussions
  • 📖 Documentation: Check this documentation for detailed guides
  • 🔧 Feature Requests: Use GitHub Issues with the enhancement label

Issue Template

When reporting bugs, please include:

  1. PCU version and command used
  2. Error message (full output with --verbose)
  3. Environment (OS, Node.js, pnpm versions)
  4. Workspace structure (pnpm-workspace.yaml, package.json)
  5. Configuration (.pcurc.json, .npmrc if relevant)
  6. Steps to reproduce the issue
  7. Expected vs actual behavior

Security Command Issues

Snyk Integration Problems

Error Message:

Error: Snyk CLI not found

Cause: Snyk CLI is not installed but --snyk flag is used.

Solutions:

# Install Snyk globally
npm install -g snyk

# Authenticate with Snyk
snyk auth

# Test Snyk installation
snyk --version

Security Fix Failures

Error Message:

Error: Unable to automatically fix vulnerabilities

Cause: Some vulnerabilities require manual intervention or major version updates.

Solutions:

# Review vulnerabilities first
pcu security --format json > security.json

# Try automated fix
pcu security --fix-vulns

# Manual package updates if needed
pcu -u --include "vulnerable-package"

Theme Command Issues

Error Message:

Error: Theme 'custom-theme' not found

Cause: Trying to set a theme that doesn't exist.

Solutions:

# See all available themes
pcu theme --list

# Use interactive theme selection
pcu theme --interactive

Interactive Mode Issues

Error Message:

Error: Interactive mode not supported in this environment

Cause: Running PCU in a non-interactive environment (CI, pipe, etc.).

Solutions:

# Use dry-run to preview changes
pcu -u --dry-run

# Use specific targets instead of interactive
pcu -u --target minor

# Use configuration file for automation
pcu -u --config .pcurc.json

Command-Specific Issues

Analyze Command Issues

Error Message:

Error: Package 'react' not found in catalog 'nonexistent'

Cause: Analyzing a package that doesn't exist in the specified catalog.

Solutions:

# List workspace catalogs
pcu workspace --stats

# Check if package exists in default catalog
pcu -a default react

# List all packages in catalog
pcu -c --catalog specific-catalog

Update Command Failures

Error Message:

Error: Failed to update package.json files

Cause: File permission issues or workspace structure problems.

Solutions:

# Check file permissions
ls -la pnpm-workspace.yaml
find packages -name "package.json" -exec ls -la {} \;

# Fix permissions if needed
chmod u+w pnpm-workspace.yaml
chmod u+w packages/*/package.json

Advanced Debugging

Memory Leak Investigation

Symptoms: PCU process memory keeps growing during operation

Debug Steps:

# Monitor memory usage
watch -n 1 'ps aux | grep pcu'

# Use Node.js memory profiling
node --inspect $(which pcu) -c

# Enable garbage collection logging
node --trace-gc $(which pcu) -c

Registry Response Issues

Symptoms: Inconsistent results or timeout errors

Debug Steps:

# Test registry connectivity
curl -I https://registry.npmjs.org/

# Check registry response time
time npm view react versions

# Use alternative registries
npm config set registry https://registry.npmmirror.com/

Configuration Inheritance Issues

Symptoms: Configuration not being applied as expected

Debug Steps:

# Check config file locations
ls -la .pcurc.json
ls -la ~/.pcurc.json
ls -la ~/.config/pcu/config.json

# Debug config loading
DEBUG=pcu:config pcu -c --verbose

# Show effective configuration
pcu config --show-effective

Was this page helpful?