Troubleshooting & FAQ

Common issues and solutions for Alprina.

Installation Issues

Command Not Found

Problem: alprina: command not found after installation

Solution:

# Check if installed
pip show alprina-cli
 
# If not installed
pip install alprina-cli
 
# If installed but not in PATH
export PATH="$HOME/.local/bin:$PATH"
 
# Add to shell profile
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Permission Denied

Problem: Permission errors during installation

Solution:

# Install for current user only
pip install --user alprina-cli
 
# Or use virtual environment (recommended)
python -m venv venv
source venv/bin/activate
pip install alprina-cli

Authentication Issues

API Key Not Accepted

Problem: API key rejected with 401 error

Solutions:

1. Verify API key is correct:

# Check stored API key
cat ~/.alprina/config.json
 
# Re-login with correct key
alprina auth login --api-key YOUR_API_KEY

2. Generate new API key:

• Go to dashboard 
• Navigate to API Keys section
• Create new key
• Update configuration

3. Check key format:

# API key should start with 'sk_live_' or 'sk_test_'
alprina auth login --api-key sk_live_...

Authentication Expired

Problem: “Token expired” error

Solution:

# Re-authenticate
alprina auth login --api-key YOUR_API_KEY
 
# Verify status
alprina auth status

Scanning Issues

Scan Fails with Error

Problem: Scans fail without clear error

Debug steps:

# Run with verbose output
alprina scan ./src --verbose
 
# Run with debug logging
alprina scan ./src --debug
 
# Check target exists
ls -la ./src
 
# Check permissions
chmod -R u+r ./src

Slow Scan Performance

Problem: Scans take too long

Solutions:

1. Use quicker profile:

alprina scan ./src --profile quick

2. Scan specific directories:

# Instead of entire project
alprina scan ./src/critical

3. Exclude large files:

alprina scan ./src --exclude "*/node_modules/*" --exclude "*/vendor/*"

4. Check network connectivity:

curl -I https://api.alprina.com

Target Not Found

Problem: “Target not found” error

Solutions:

# Use absolute path
alprina scan /full/path/to/src
 
# Verify path exists
ls -la ./src
 
# Check current directory
pwd
 
# Use relative path from current directory
alprina scan ./src

Credit & Billing Issues

Out of Credits

Problem: “Insufficient credits” error

Solutions:

1. Check usage:

alprina billing status

2. Upgrade plan:

• Visit pricing page 
• Select higher tier
• Complete checkout

3. Wait for reset:

• Credits reset monthly
• Check reset date: alprina billing status

Unexpected Charges

Problem: Charged for more credits than expected

Investigation:

# View usage details
alprina billing usage
 
# List recent scans
alprina scans list --limit 50
 
# Check comprehensive scans (cost 2 credits)
alprina scans list --profile comprehensive

Remember:

• Standard scan: 1 credit
• Quick scan: 0.5 credits
• Comprehensive scan: 2 credits

API Issues

Rate Limiting

Problem: “Rate limit exceeded” (429) error

Solutions:

1. Wait and retry:

# Automatic retry with exponential backoff
alprina scan ./src --retry 3

2. Upgrade tier:

• Free: 10 req/min
• Developer: 60 req/min
• Pro: 300 req/min

3. Implement delays:

# In scripts
for dir in */; do
  alprina scan "$dir"
  sleep 2  # Wait between scans
done

Connection Errors

Problem: Cannot connect to API

Solutions:

# Check internet connection
ping api.alprina.com
 
# Check API status
curl https://api.alprina.com/health
 
# Try with proxy
export HTTPS_PROXY=http://proxy:8080
alprina scan ./src
 
# Check firewall rules
# Alprina requires outbound HTTPS (443)

Output & Report Issues

Invalid JSON Output

Problem: JSON output is malformed

Solutions:

# Ensure valid output path
alprina scan ./src --output results.json
 
# Verify JSON syntax
cat results.json | python -m json.tool
 
# Re-run scan
alprina scan ./src --output results.json --overwrite

Missing Findings

Problem: Expected vulnerabilities not detected

Investigation:

1. Check scan profile:

# Use comprehensive profile
alprina scan ./src --profile comprehensive

2. Verify target:

# Ensure correct directory
ls -la ./src

3. Check language detection:

# Specify language explicitly
alprina scan ./src --language python

4. Review exclusions:

# Check what's being excluded
alprina scan ./src --verbose

CI/CD Issues

GitHub Actions Failing

Problem: Workflow fails with authentication error

Solutions:

1. Verify secret exists:

• Go to Settings → Secrets
• Confirm ALPRINA_API_KEY exists
• Regenerate if needed

2. Check secret usage:

env:
  ALPRINA_API_KEY: ${{ secrets.ALPRINA_API_KEY }}

3. Test locally:

export ALPRINA_API_KEY="your_key"
alprina scan ./src

Build Timeout

Problem: CI pipeline times out

Solutions:

# Add timeout
jobs:
  scan:
    timeout-minutes: 15
 
# Use quick profile
- run: alprina scan ./src --profile quick
 
# Cache dependencies
- uses: actions/cache@v3
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip

Integration Issues

Webhook Not Receiving Events

Problem: Webhook endpoint not called

Debug steps:

1. Verify webhook configuration:

curl -X GET https://api.alprina.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY"

2. Check endpoint accessibility:

# Endpoint must be publicly accessible
curl -X POST https://your-domain.com/webhooks/alprina \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

3. Review delivery logs:

# Check webhook delivery history
curl https://api.alprina.com/v1/webhooks/{webhook_id}/deliveries \
  -H "Authorization: Bearer YOUR_API_KEY"

4. Verify signature verification:

// Ensure signature validation is correct
const signature = req.headers['x-alprina-signature'];

Frequently Asked Questions

General

Q: Is Alprina free to use?

A: Yes, Alprina offers a free tier with 10 scans per month. Paid plans start at $29/month.

Q: What languages does Alprina support?

A: Python, JavaScript, TypeScript, Java, Go, Rust, PHP, Ruby, C/C++, and more.

Q: Can I use Alprina offline?

A: Local scans work offline, but remote scans and some features require internet connectivity.

Q: How accurate is Alprina?

A: Alprina has >95% accuracy with low false positive rates. Always verify critical findings.

Security & Privacy

Q: Is my code sent to external servers?

A: Local scans analyze code locally. Remote scans send minimal context to our secure API for AI analysis.

Q: How is my data stored?

A: Scan results are encrypted at rest and in transit. We follow SOC 2 compliance standards.

Q: Can I delete my scan history?

A: Yes, from dashboard → Scans → Select scan → Delete. Or via API:

curl -X DELETE https://api.alprina.com/v1/scans/{scan_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Features

Q: Can Alprina fix vulnerabilities automatically?

A: Alprina provides detailed remediation guidance. Use alprina mitigate for fix suggestions.

Q: Does Alprina integrate with Jira/Slack?

A: Yes, via webhooks. See Integrations for setup guides.

Q: Can I customize scan rules?

A: Yes, using security policies. See Policies Guide.

Billing

Q: What counts as a credit?

A: 1 standard scan = 1 credit. Quick scans = 0.5 credits. Comprehensive = 2 credits.

Q: When do credits reset?

A: Credits reset on the 1st of each month based on your billing cycle.

Q: What happens if I exceed my credit limit?

A: Free tier: scans blocked. Paid tiers: overage charged at per-credit rate ($0.50 or$0.30).

Q: Can I get a refund?

A: Contact support@alprina.com for refund requests.

Technical

Q: What LLM models does Alprina use?

A: Claude 3.5 Sonnet (default) and GPT-4. Configurable via --llm flag.

Q: Can I self-host Alprina?

A: The CLI is open source. The API is a managed service. Contact sales@alprina.com for enterprise options.

Q: Does Alprina support monorepos?

A: Yes, scan different directories and aggregate results:

alprina scan ./frontend --output frontend.json
alprina scan ./backend --output backend.json

Still Need Help?

Contact Support

• Email: support@alprina.com
• GitHub Issues: github.com/alprina/alprina-cli/issues 
• Discussions: github.com/alprina/alprina-cli/discussions 
• Discord: discord.gg/alprina 

Include in Support Requests

1. Alprina version:

alprina --version

2. Python version:

python --version

3. Operating system:

uname -a  # Linux/Mac
systeminfo  # Windows

4. Error logs:

alprina scan ./src --debug > debug.log 2>&1

5. Configuration:

cat ~/.alprina/config.json

Error Code Reference