General Troubleshooting¶

Section: Troubleshooting | Article 45
Audience: System Administrators
Last Updated: 2026-04-07

Overview¶

This article covers common RP-PAM issues that apply to all platforms. For platform-specific troubleshooting, see: - Windows-Specific Issues - Linux-Specific Issues - Database Issues - LDAP and LDAPS Issues - HA and Cluster Issues

Quick Diagnostic Steps¶

Before diving into specific issues, run these checks:

1. Check Service Status¶

Windows:

Get-Service -Name "RpPam"

Linux:

sudo systemctl status rppam

2. Check Health Endpoint¶

curl -s http://localhost:7101/system/health/ping | jq .

PowerShell:

Invoke-RestMethod http://localhost:7101/system/health/ping

A healthy response:

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": "2.04:30:15",
  "database": "connected",
  "vault": "operational"
}

3. Check Recent Logs¶

Windows:

Get-Content "C:\ProgramData\Ravenphyre\RP-PAM\Logs\rppam-$(Get-Date -Format 'yyyyMMdd').log" -Tail 30

Linux:

sudo journalctl -u rppam --since "30 minutes ago" --no-pager

Common Issues¶

#	Symptom	Cause	Solution
1	Health ping returns HTTP 500	Database connection lost or vault initialization failed	See Health Ping 500 below
2	"License expired" error on login	License validity period ended	See License Expired below
3	Portal shows blank white page	Frontend assets not loaded or CORS misconfiguration	See Portal Blank Page below
4	"CEK not found" error	Content Encryption Key missing or corrupted	See CEK Not Found below
5	Service won't start	Configuration error, port conflict, or missing dependency	See Service Won't Start below
6	Port conflict on 7101	Another process is using the RP-PAM port	See Port Conflict below
7	"Unauthorized" on all API calls	JWT expired or signing key rotated	See Unauthorized Errors below
8	Grants not expiring	Background job scheduler stopped	See Grants Not Expiring below
9	Slow API responses	Database query performance or resource exhaustion	See Slow Performance below
10	"Module not found"	Module not registered or disabled	See Module Not Found below

Health Ping Returns 500¶

The /system/health/ping endpoint returns HTTP 500 when a critical subsystem has failed.

Step 1: Check the detailed health endpoint:

# PowerShell
Invoke-RestMethod http://localhost:7101/system/health/detail `
    -Headers @{ Authorization = "Bearer $adminJwt" }

# curl
curl -s http://localhost:7101/system/health/detail \
  -H "Authorization: Bearer $ADMIN_JWT" | jq .

Step 2: The response identifies which subsystem failed:

{
  "status": "unhealthy",
  "checks": {
    "database": { "status": "unhealthy", "error": "Connection refused" },
    "vault": { "status": "healthy" },
    "scheduler": { "status": "healthy" }
  }
}

Step 3: Address the failing subsystem:

Failing Check	Action
`database`	Check database connectivity — see Database Issues
`vault`	Check encryption keys — see CEK Not Found below
`scheduler`	Restart the service — the background scheduler may have crashed

License Expired¶

Symptoms: - Users see "License expired" when logging in - API returns 403 with "error": "license_expired"

Solution:

Check the current license status:

Invoke-RestMethod http://localhost:7101/api/v1/admin/license `
    -Headers @{ Authorization = "Bearer $adminJwt" }

curl -s http://localhost:7101/api/v1/admin/license \
  -H "Authorization: Bearer $ADMIN_JWT" | jq .

If the license is expired, activate a new license:
Online: See License Activation (Online)
Offline: See License Activation (Offline)

If you have renewed but the license file has not been applied, apply it:

Invoke-RestMethod -Uri "https://rppam.corp.local:7101/api/v1/admin/license" `
    -Method PUT `
    -Headers @{ Authorization = "Bearer $adminJwt" } `
    -ContentType "application/json" `
    -Body '{"licenseKey": "your-new-license-key"}'

Note: RP-PAM provides a 7-day grace period after license expiry. During the grace period, existing functionality continues but new module configurations are blocked.

Portal Shows Blank Page¶

Symptoms: - Navigating to https://rppam.corp.local:7101 shows a blank white page - Browser console shows 404 errors for .js or .css files

Solution:

Check the portal files exist:

Windows:

Test-Path "C:\Program Files\Ravenphyre\RP-PAM\wwwroot\index.html"

Linux:

ls -la /opt/rppam/wwwroot/index.html

If files are missing, the installation may be incomplete. Re-run the installer or re-extract the deployment package.
If files exist, check for CORS or base path issues in the browser developer console (F12):
If errors mention CORS, verify the portal.allowedOrigins setting in rppam.config includes your access URL.
If errors show wrong paths, verify portal.basePath is set correctly (default: /).
Clear browser cache — stale cached assets from a previous version can cause loading failures.

CEK Not Found¶

Symptoms: - Error in logs: CEK not found for purpose: vault (or credentials, audit) - Vault operations fail with 500 errors

Cause: The Content Encryption Key is missing from the database or cannot be decrypted (KEK issue).

Solution:

Check the key hierarchy:

Invoke-RestMethod -Uri "https://rppam.corp.local:7101/api/v1/admin/encryption/status" `
    -Headers @{ Authorization = "Bearer $adminJwt" }

curl -s "https://rppam.corp.local:7101/api/v1/admin/encryption/status" \
  -H "Authorization: Bearer $ADMIN_JWT" | jq .

If the KEK is healthy but CEKs are missing, the CEKs may need to be re-generated (this happens if the database was restored from a backup without the corresponding key backup):

Invoke-RestMethod -Uri "https://rppam.corp.local:7101/api/v1/admin/encryption/repair" `
    -Method POST `
    -Headers @{ Authorization = "Bearer $adminJwt" }

If the KEK is also unhealthy, you may need to restore from a key backup. Contact Ravenphyre Support for assistance.

Warning: If CEKs cannot be recovered, vault data encrypted with those keys is unrecoverable. This is why regular backups (including encryption key backups) are critical.

Service Won't Start¶

Symptoms: - Service fails to start (Windows: error 1067; Linux: systemctl status shows failed)

Step 1: Check the logs for startup errors:

Windows:

Get-Content "C:\ProgramData\Ravenphyre\RP-PAM\Logs\rppam-$(Get-Date -Format 'yyyyMMdd').log" -Tail 50

Linux:

sudo journalctl -u rppam --since "5 minutes ago" --no-pager

Step 2: Common startup failures:

Log Message	Cause	Solution
"Address already in use"	Port 7101 is taken	See Port Conflict below
"Invalid configuration"	Syntax error in `rppam.config`	Validate JSON: use a JSON linter or `jq . rppam.config`
"Database connection failed"	Database unreachable	Check database server status and connection string
"Certificate not found"	TLS cert path wrong or file missing	Verify `tls.certPath` and `tls.keyPath` in config
"Insufficient permissions"	Service account lacks required rights	See Windows Issues or Linux Issues

Port Conflict¶

Symptoms: - Service won't start - Log shows "Address already in use" or "port 7101 is already in use"

Step 1: Find what is using the port:

Windows:

netstat -ano | Select-String ":7101"
# Note the PID, then:
Get-Process -Id <PID> | Format-Table Name, Id, Path

Linux:

sudo ss -tlnp | grep 7101

Step 2: Either stop the conflicting process or change the RP-PAM port in rppam.config:

{
  "server": {
    "port": 7102
  }
}

Then restart the service and update any firewall rules, load balancer configurations, and bookmarks.

Unauthorized on All API Calls¶

Symptoms: - All API requests return 401 Unauthorized - Portal login works but subsequent API calls fail

Possible causes:

JWT expired — Tokens have a default lifetime of 60 minutes. Re-authenticate:

curl -s -X POST "https://rppam.corp.local:7101/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "your-password"}' | jq .token

Signing key rotated — If the JWT signing key was rotated, all existing tokens become invalid. Users must log in again.
Clock skew — If the server clock is more than 5 minutes off from the token issuer, JWTs will be rejected. Synchronize NTP:
```
# Linux
sudo timedatectl set-ntp true
```
```
# Windows
w32tm /resync
```

Grants Not Expiring¶

Symptoms: - Grants remain active past their expiry time - Temporary database users or SSH keys are not being cleaned up

Cause: The background job scheduler may have stopped.

Solution:

Check scheduler status:

curl -s http://localhost:7101/system/health/detail \
  -H "Authorization: Bearer $ADMIN_JWT" | jq '.checks.scheduler'

If the scheduler shows "unhealthy", restart the service:

Restart-Service -Name "RpPam"   # Windows

sudo systemctl restart rppam   # Linux

After restart, expired grants will be processed within 60 seconds.

Slow API Responses¶

Symptoms: - API responses take more than 2-3 seconds - Portal feels sluggish

Step 1: Check system resources:

Windows:

Get-Process -Name "RpPam*" | Format-Table Name, CPU, WorkingSet64

Linux:

top -bn1 | head -20

Step 2: Check database performance: - See Database Issues for query timeout and connection pool issues.

Step 3: If CPU or memory is exhausted, consider: - Adding more resources to the server - Enabling HA to distribute load across multiple nodes - Reviewing module configurations for excessive polling intervals

Module Not Found¶

Symptoms: - API returns "error": "module_not_found" when creating a grant - Portal does not show expected resources

Solution:

List registered modules:

curl -s "https://rppam.corp.local:7101/api/v1/modules" \
  -H "Authorization: Bearer $ADMIN_JWT" | jq '.[].moduleType'

If the module is not listed, register it (see the relevant module article: AD, Entra ID, SSH, Database).

If the module is listed but "enabled": false, enable it:

curl -s -X PATCH "https://rppam.corp.local:7101/api/v1/modules/$MODULE_ID" \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}' | jq .

Next Steps¶

Windows-Specific Issues
Linux-Specific Issues
Database Issues
Log Collection and Submission — Collect logs for support
Diagnostic Health Check — Run a comprehensive health check before contacting support
Support Contact — Contact Ravenphyre