Troubleshooting

Solutions to common issues when using the PromptGuard CLI.

Installation Issues

Command not found: promptguard

Problem: After installation, running promptguard shows “command not found”Solutions:

Check if /usr/local/bin is in PATH:

echo $PATH | grep "/usr/local/bin"

If not found, add it:

# For Zsh (macOS default)
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# For Bash
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Install to user directory:

mkdir -p ~/bin
mv promptguard ~/bin/
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Verify installation:

which promptguard
# Should show: /usr/local/bin/promptguard

Permission denied when installing

Problem: Install script fails with permission errorsSolutions:

Run with sudo:

curl -fsSL https://raw.githubusercontent.com/acebot712/promptguard-cli/main/install.sh | sudo sh

Or install to user directory (no sudo needed):

# Download binary
curl -fsSL https://github.com/acebot712/promptguard-cli/releases/latest/download/promptguard-macos-arm64 -o promptguard
chmod +x promptguard

# Install to ~/bin
mkdir -p ~/bin
mv promptguard ~/bin/
export PATH="$HOME/bin:$PATH"

Cannot execute binary file

Problem: Binary won’t run, shows “cannot execute binary file”Cause: Wrong architecture downloadedSolution:

Check your system:

uname -sm
# Darwin arm64    → Use promptguard-macos-arm64
# Darwin x86_64   → Use promptguard-macos-x86_64
# Linux x86_64    → Use promptguard-linux-x86_64
# Linux aarch64   → Use promptguard-linux-arm64

Download correct binary:

# Example for macOS M1/M2/M3
curl -fsSL https://github.com/acebot712/promptguard-cli/releases/latest/download/promptguard-macos-arm64 -o promptguard
chmod +x promptguard
sudo mv promptguard /usr/local/bin/

SSL certificate verification failed

Problem: Download fails with SSL/TLS errorsSolution (Linux):

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install ca-certificates

# CentOS/Fedora
sudo yum install ca-certificates

Solution (macOS):

# Update certificates
brew install openssl

Initialization Issues

No SDKs detected

Problem: promptguard scan finds no LLM SDKsPossible causes:

No SDK initialization in code (only imports):

// ✗ Only import - not detected
import OpenAI from 'openai';

// ✓ Initialization - detected
const client = new OpenAI({...});

Files in excluded directories: Check node_modules, dist, build, .venv, venv are excluded by default
Wrong file extension: CLI scans: .ts, .tsx, .js, .jsx, .py Skips: .json, .md, .txt

Solution:

# Check what files are being scanned
promptguard scan

# Verify your code has SDK initialization
grep -r "new OpenAI" src/
grep -r "OpenAI(" .  # Python

Invalid API key format

Problem: Error: “Invalid API key format”Solution:API keys must start with:

Test keys: pg_sk_test_
Production keys: pg_sk_prod_

Get a valid key:

Visit app.promptguard.co/settings/api-keys
Click “Generate New Key”
Copy the key (starts with pg_sk_test_ or pg_sk_prod_)
Run: promptguard init --api-key pg_sk_test_xxxxx

Permission denied writing to .env

Problem: Cannot write to .env fileSolution:

Check file permissions:

ls -la .env
# Should show -rw-r--r-- or similar

Fix permissions:
```
chmod 644 .env
```

If .env doesn’t exist:

touch .env
chmod 644 .env
promptguard init --api-key pg_sk_test_xxx

Already initialized error

Problem: “PromptGuard is already initialized”Solution:

Check status:
```
promptguard status
```
Re-apply changes:
```
promptguard apply
```

Or completely reset:

promptguard revert -y
promptguard init --api-key pg_sk_test_xxx

Runtime Issues

Requests not showing in dashboard

Problem: Application runs but no requests appear in dashboardDebugging steps:

Verify transformation was applied:

# Check if baseURL was added
grep -r "baseURL" src/
grep -r "base_url" .  # Python

# Or check specific file
cat src/ai.ts | grep baseURL

Verify API key in code:

# Check .env file
cat .env | grep PROMPTGUARD_API_KEY

# Verify app loads it
# In your code:
console.log(process.env.PROMPTGUARD_API_KEY);  // TypeScript
print(os.environ.get("PROMPTGUARD_API_KEY"))   # Python

Test connectivity:
```
promptguard test
```
Check if app is actually making LLM calls:
- Trigger a feature that uses AI
- Check app logs for errors
- Verify LLM response is returned
Verify correct API key in dashboard:
- Dashboard shows requests for the specific API key
- Ensure you’re looking at the right project

baseURL was not added to code

Problem: Transformation didn’t add baseURL/base_urlPossible causes:

Already has baseURL: CLI skips if already configured
Unsupported SDK pattern: CLI looks for standard initialization patterns

Solution:

Check if already present:
```
cat src/file.ts | grep baseURL
```

Manually add if needed:

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: "https://api.promptguard.co/api/v1"  // Add this
});

Then run:

promptguard config  # Verify configuration

Application crashes after init

Problem: App crashes or throws errors after PromptGuard initializationDebugging:

Check error message: Common errors:
- baseURL is not a valid option → Old SDK version
- ECONNREFUSED → Network issue
- API key invalid → Wrong key

Verify SDK version:

# Check package.json
cat package.json | grep openai

# Update if needed
npm install openai@latest

Test without PromptGuard:

# Disable temporarily
promptguard disable

# Run app
npm run dev

# If works, re-enable
promptguard enable

Check proxy URL:

# Verify URL is correct
promptguard config | grep "Proxy URL"

# Should be: https://api.promptguard.co/api/v1

API calls timing out

Problem: LLM API calls are very slow or timeoutPossible causes:

Network latency to PromptGuard proxy
Slow upstream LLM provider
Heavy security scanning

Solution:

Test direct connection:

curl -I https://api.promptguard.co/api/v1/chat/completions
# Should return 200 OK quickly

Check dashboard for latency: Visit app.promptguard.co/dashboard
- View “Response Time” metrics
- PromptGuard adds ~10-50ms typically

Increase timeout in code:

const client = new OpenAI({
  baseURL: "https://api.promptguard.co/api/v1",
  timeout: 60000  // 60 seconds
});

Contact support if persistent: [email protected]

Configuration Issues

Config file corrupted

Problem: .promptguard.json is invalid or corruptedSolution:

Validate JSON:

cat .promptguard.json | jq
# If error, JSON is invalid

Delete and reinitialize:

rm .promptguard.json
promptguard init --api-key pg_sk_test_xxx

Or manually fix: Edit .promptguard.json with proper JSON syntax

Can't revert changes

Problem: promptguard revert doesn’t restore filesPossible causes:

No backup files (.bak files deleted)
Backups disabled during init

Solution:

Check for backups:
```
find . -name "*.bak"
```

If backups exist:

# Manually restore
for f in $(find . -name "*.bak"); do
  original="${f%.bak}"
  cp "$f" "$original"
done

If no backups, use git:
```
git checkout -- .
git clean -fd
```

Always keep backups. Never use --no-backup flag.

Multiple .promptguard.json files

Problem: Multiple config files in monorepo causing confusionSolution:Each project should have its own config:

monorepo/
├── packages/
│   ├── frontend/
│   │   ├── .promptguard.json  ← Separate
│   │   └── .env
│   └── backend/
│       ├── .promptguard.json  ← Separate
│       └── .env

Run CLI in each directory:

cd packages/frontend
promptguard init

cd ../backend
promptguard init

Command-Specific Issues

promptguard test fails

Problem: promptguard test shows errorsCommon failures:

API key invalid:
```
✗ API key is invalid
```
→ Get new key from dashboard
Proxy unreachable:
```
✗ Connection failed: Network error
```
→ Check internet connection → Verify https://api.promptguard.co is accessible
Config not found:
```
Error: Not initialized
```
→ Run promptguard init first

promptguard disable/enable not working

Problem: Disable/enable commands don’t change filesSolution:

Check status:

promptguard status
# Should show: Status: Disabled / Enabled

Verify backups exist:
```
find . -name "*.bak"
```

Manually check files:

# After disable, baseURL should be gone
cat src/ai.ts | grep baseURL
# Should return nothing

# After enable, baseURL should be present
promptguard enable
cat src/ai.ts | grep baseURL
# Should show: baseURL: "..."

Getting Help

If you’re still stuck:

Run Diagnostics

promptguard doctor

Checks common issues

Check Logs

promptguard logs

View activity logs

Email Support

[email protected]

GitHub Issues

Report bugs or request features

Collecting Debug Information

When reporting issues, include:

# 1. CLI version
promptguard --version

# 2. Operating system
uname -a

# 3. Configuration (remove API key first!)
cat .promptguard.json | sed 's/"api_key": ".*"/"api_key": "REDACTED"/'

# 4. Scan results
promptguard scan

# 5. Test results
promptguard test

# 6. Error message (full output)
promptguard <command> 2>&1 | tee error.log

Send the output to [email protected]

Next Steps

Commands Reference

Full command documentation

Configuration

Advanced configuration options

Email Support

Getting Started

CLI & Editor Tools

Integration Guides

Security & Policies

Monitoring & Analytics

Advanced

Examples

Troubleshooting

Troubleshooting

Installation Issues

Initialization Issues

Runtime Issues

Configuration Issues

Command-Specific Issues

Getting Help

Run Diagnostics

Check Logs

GitHub Issues

Collecting Debug Information

Next Steps

Commands Reference

Configuration

Getting Started

CLI & Editor Tools

Integration Guides

Security & Policies

Monitoring & Analytics

Advanced

Examples

​Troubleshooting

​Installation Issues

​Initialization Issues

​Runtime Issues

​Configuration Issues

​Command-Specific Issues

​Getting Help

Run Diagnostics

Check Logs

Email Support

GitHub Issues

​Collecting Debug Information

​Next Steps

Commands Reference

Configuration

Troubleshooting

Installation Issues

Initialization Issues

Runtime Issues

Configuration Issues

Command-Specific Issues

Getting Help

Collecting Debug Information

Next Steps