Troubleshooting - PRPM Documentation

Installation Issues

Command Not Found After Installation

Problem: After running npm install -g prpm, the prpm command is not found. Solutions:

Check if npm global bin is in your PATH:

npm config get prefix
# Should output something like /usr/local or ~/.npm-global

Add npm global bin to PATH (if needed):

# For bash
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For zsh
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Use npx as alternative:

npx prpm install @username/typescript-rules

Reinstall with correct permissions:

# On Linux/Mac, may need sudo
sudo npm install -g prpm

Permission Errors During Installation

Problem: EACCES or permission denied errors when installing globally. Solutions:

Change npm’s default directory (recommended):

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
source ~/.profile
npm install -g prpm

Use sudo (less secure):
sudo npm install -g prpm

Package Installation Issues

Package Not Found

Problem: Error: Package 'package-name' not found Diagnose:

# Search for the package
prpm search package-name

# Check exact name
prpm info @username/typescript-rules

Common causes:

Typo in package name:

# Check the exact name
prpm search typescript
# Then use the exact package name from search results
prpm install @username/typescript-rules

Private package without authentication:

# Login first
prpm login
prpm install @username/private-package

Package doesn’t exist: Verify on registry.prpm.dev

File Already Exists

Problem: Error: File already exists at destination Solutions:

Check what’s already installed:
prpm list --verbose

Uninstall conflicting package first:

prpm uninstall conflicting-package
prpm install @username/new-package

Force reinstall:

prpm install @username/typescript-rules --force

Install with custom name:

prpm install @username/typescript-rules --as different-name

Download/Network Errors

Problem: Timeouts or connection errors during installation. Solutions:

Check internet connection:
ping registry.prpm.dev

Check registry URL:

prpm config get registry
# Should be: https://registry.prpm.dev

Try with custom timeout:

# Set higher timeout (in seconds)
export REQUEST_TIMEOUT=60
prpm install @username/typescript-rules

Check firewall/proxy settings:

# If behind a proxy
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

Retry installation:

prpm install @username/typescript-rules

Integrity Check Failed

Problem: Error: Package integrity check failed Solutions:

Clear cache and retry:

rm -rf ~/.prpm/cache
prpm install @username/typescript-rules

Force reinstall:

prpm install @username/typescript-rules --force

Report issue: This may indicate a corrupted package in the registry

Authentication Issues

Problem: Unable to authenticate with the registry. Solutions:

Clear existing auth and retry:
prpm config delete token prpm login

Check registry URL:

prpm config get registry
# Should match your intended registry

Use token directly (if you have one):
prpm login --token YOUR_AUTH_TOKEN
Check browser is opening:
- If browser doesn’t open, copy URL from terminal
- Complete authentication manually

Permission Denied When Publishing

Problem: Error: Insufficient permissions to publish Diagnose:

# Check if logged in
prpm whoami

# Verify package name doesn't conflict
prpm info @username/typescript-rules

Solutions:

Ensure you’re logged in:
prpm login

Use correct namespace:

# Can only publish to your own namespace
# In prpm.json:
{
  "name": "@username/typescript-rules"
}

Check package doesn’t already exist:

prpm search package-name
# If exists, increment version or choose different name

Publishing Issues

Validation Errors

Problem: Error: Package validation failed Solutions:

Validate your manifest:
prpm schema --validate prpm.json

Check required fields:

{
  "name": "@username/typescript-rules",
  "version": "1.0.0",
  "description": "Package description",
  "format": "cursor",
  "subtype": "rule",
  "author": "Your Name",
  "files": [".cursorrules"]
}

Ensure files exist:

# Check that all files in "files" array exist
ls -la .cursorrules

Validate version format:
- Must be valid semver: 1.0.0, 2.1.3, etc.
- Cannot republish same version

Package Already Exists

Problem: Error: Package version already exists Solutions:

Increment version:

{
  "version": "1.0.1"  // Increment from 1.0.0
}

Check existing versions:
prpm info @username/typescript-rules
Use semantic versioning:
- Patch: 1.0.1 (bug fixes)
- Minor: 1.1.0 (new features)
- Major: 2.0.0 (breaking changes)

Files Not Included in Package

Problem: Published package missing expected files. Solutions:

Check files array in prpm.json:

{
  "files": [
    ".cursorrules",
    "README.md",
    "examples/"
  ]
}

Use dry-run to preview:

prpm publish --dry-run
# Shows what will be included

Verify file paths are correct:

# List files that match patterns
ls -la .cursorrules
ls -la README.md

Lock File Issues

Corrupted prpm.lock

Problem: Error: Invalid lock file format Solutions:

Validate JSON syntax:

cat prpm.lock | jq .
# Shows where JSON is invalid

Rebuild lock file:

# Backup first
cp prpm.lock prpm.lock.backup

# Remove and regenerate
rm prpm.lock
prpm index

Manual fix (if you know what’s wrong):
vim prpm.lock # Fix JSON syntax errors

Lock File Out of Sync

Problem: Lock file doesn’t match installed files. Solutions:

Rebuild from installed files:
prpm index

Reinstall packages:

# List packages first
prpm list

# Reinstall each
prpm install @username/typescript-rules --force

Update/Upgrade Issues

No Updates Available (But You Know There Should Be)

Problem: prpm outdated shows no updates despite new versions existing. Solutions:

Check registry directly:

prpm info @username/typescript-rules
# Shows latest version

Clear cache:
rm -rf ~/.prpm/cache prpm outdated
Force update:
prpm update package-name --force

Update Fails Partway Through

Problem: Update starts but fails, leaving package in inconsistent state. Solutions:

Uninstall and reinstall:

prpm uninstall package-name
prpm install @username/typescript-rules

Check file permissions:

ls -la .cursor/rules/
# Ensure you have write permissions

Cleanup and retry:

# Remove partial installation
rm -f .cursor/rules/package-file.md
prpm install @username/typescript-rules

Format-Specific Issues

Cursor: Rules Not Being Applied

Problem: Installed Cursor rules don’t seem to affect the AI. Solutions:

Check MDC header is present:

head -5 .cursor/rules/your-rule.mdc
# Should show frontmatter:
# ---
# title: Your Rule
# tags: []
# ---

Restart Cursor:
- Close and reopen Cursor
- Or reload window: Cmd/Ctrl + Shift + P → “Reload Window”

Check file is in correct location:

ls -la .cursor/rules/
# Files should be .mdc or .cursorrules

Verify file syntax:

# Open in Cursor and check for errors
cursor .cursor/rules/your-rule.mdc

Claude: Skills Not Loading

Problem: Claude skills installed but not available. Solutions:

Check directory structure:

ls -la .claude/skills/
# Should have subdirectories with SKILL.md files

# Example structure:
# .claude/skills/
#   └── my-skill/
#       └── SKILL.md

Verify SKILL.md format:

# Skill Name

## Description
What this skill does

## Instructions
How to use it

Restart Claude application

Configuration Issues

Config Not Persisting

Problem: Configuration changes don’t persist after restart. Solutions:

Check config file location:

ls -la ~/.prpmrc
# Should exist and be writable

Check file permissions:
chmod 600 ~/.prpmrc

Manually edit config:

vim ~/.prpmrc
# Format:
# registry=https://registry.prpm.dev
# token=your-token

Custom Registry Not Working

Problem: Setting custom registry doesn’t take effect. Solutions:

Verify config:
prpm config get registry

Set via environment variable:

export PRPM_REGISTRY_URL=https://custom.registry.dev
prpm search test

Set globally:

prpm config set registry https://custom.registry.dev

Performance Issues

Slow Package Installation

Problem: Package installation takes longer than expected. Diagnose:

# Check network speed
curl -o /dev/null https://registry.prpm.dev/test-file

# Check disk space
df -h

# Check disk I/O
iostat -x 1

Solutions:

Clear cache:
rm -rf ~/.prpm/cache

Check DNS resolution:

nslookup registry.prpm.dev
# Should resolve quickly

Use wired connection if on WiFi
Close other applications using network/disk

High Memory Usage

Problem: PRPM CLI using excessive memory. Solutions:

Update to latest version:
npm update -g prpm

Use smaller batch operations:

# Instead of:
prpm install pkg1 pkg2 pkg3 ... pkg50

# Do:
prpm install pkg1 pkg2 pkg3
prpm install pkg4 pkg5 pkg6

Debugging

Enable Verbose Logging

Get detailed output for debugging:

# Enable debug logs
export DEBUG=prpm:*
prpm install @username/typescript-rules

# Or for specific command
prpm install @username/typescript-rules --verbose

Check PRPM Version

prpm --version

View Full Error Stack

# Set environment variable
export NODE_ENV=development
prpm install @username/typescript-rules
# Will show full error stack traces

Inspect Lock File

# Pretty print lock file
cat prpm.lock | jq .

# Check specific package
cat prpm.lock | jq '.packages[] | select(.id=="package-name")'

Network Debugging

# Test registry connection
curl -I https://registry.prpm.dev

# Test package download
curl -I https://registry.prpm.dev/packages/@username/typescript-rules

Getting Additional Help

If you’ve tried these solutions and still have issues:

Check GitHub Issues:
- https://github.com/pr-pm/prpm/issues
- Search for similar issues
- Comment on existing issues or create new one

Provide detailed information when reporting:

# Include this information:
prpm --version
node --version
npm --version
uname -a  # or `ver` on Windows

# Include error message and full command
# Include relevant config
prpm config list

Join the community:
- GitHub Discussions

Common Error Messages Explained

`ENOENT: no such file or directory`

Meaning: File or directory doesn’t exist. Solution: Check that the path is correct and the file exists.

`EACCES: permission denied`

Meaning: Insufficient permissions to access file/directory. Solution: Check permissions with ls -la, use sudo if appropriate, or change ownership.

`EISDIR: illegal operation on a directory`

Meaning: Trying to perform file operation on a directory. Solution: Check that your target is a file, not a directory.

`EEXIST: file already exists`

Meaning: Trying to create something that already exists. Solution: Use --force flag or remove existing file first.

`Invalid semver version`

Meaning: Version number doesn’t follow semantic versioning. Solution: Use format X.Y.Z (e.g., 1.0.0, 2.1.3).

`Package not found in registry`

Meaning: Package doesn’t exist or you lack access. Solution: Check package name, ensure you’re authenticated if private.

`Authentication required`

Meaning: Need to login to access resource. Solution: Run prpm login.

`Rate limit exceeded`

Meaning: Too many requests to registry. Solution: Wait a few minutes and retry.

​Installation Issues

​Command Not Found After Installation

​Permission Errors During Installation

​Package Installation Issues

​Package Not Found

​File Already Exists

​Download/Network Errors

​Integrity Check Failed

​Authentication Issues

​Login Fails

​Permission Denied When Publishing

​Publishing Issues

​Validation Errors

​Package Already Exists

​Files Not Included in Package

​Lock File Issues

​Corrupted prpm.lock

​Lock File Out of Sync

​Update/Upgrade Issues

​No Updates Available (But You Know There Should Be)

​Update Fails Partway Through

​Format-Specific Issues

​Cursor: Rules Not Being Applied

​Claude: Skills Not Loading

​Configuration Issues

​Config Not Persisting

​Custom Registry Not Working

​Performance Issues

​Slow Package Installation

​High Memory Usage

​Debugging

​Enable Verbose Logging

​Check PRPM Version

​View Full Error Stack

​Inspect Lock File

​Network Debugging

​Getting Additional Help

​Common Error Messages Explained

​ENOENT: no such file or directory

​EACCES: permission denied

​EISDIR: illegal operation on a directory

​EEXIST: file already exists

​Invalid semver version

​Package not found in registry

​Authentication required

​Rate limit exceeded