-
Notifications
You must be signed in to change notification settings - Fork 70
FAQ and Troubleshooting
This FAQ is rewritten for CPA Manager Plus. Some old CPA-Manager troubleshooting steps mentioned "External Usage Service" in CPA panel mode. That workflow is not supported in Plus.
Use the Manager Server-hosted panel for CPAMP analytics:
http://<host>:18317/management.html
| Goal | Recommended mode |
|---|---|
| New deployment | Full Docker / Manager Server mode |
| Request monitoring, historical statistics, model prices, aliases, import/export | Full Docker / Manager Server mode |
| Existing CPA panel only, without Manager Server analytics | CPA panel mode |
| No Docker | Native Manager Server mode |
CPA panel mode is intentionally limited. It does not configure Manager Server and does not read Manager Server SQLite data.
Changing the CPA panel repository only changes the frontend served by CPA.
Request monitoring and historical analytics require Manager Server:
docker run -d \
--name cpa-manager-plus \
--restart unless-stopped \
-p 18317:18317 \
-v cpa-manager-plus-data:/data \
seakee/cpa-manager-plus:latestOpen:
http://<host>:18317/management.html
Complete setup with:
CPAMP Admin Key
CPA URL
CPA Management Key
Do not look for the old "External Usage Service" setting in Plus.
Manager Server is already configured.
Use the CPAMP admin key:
cmp_admin_...
Do not use the CPA Management Key on the CPAMP login form.
If the admin key is lost, use Reset Admin Key.
| Place | Key |
|---|---|
| CPAMP Full Docker/native login | CPAMP Admin Key |
| CPAMP first setup CPA connection | CPA Management Key |
| CPA panel mode login | CPA Management Key |
| Normal model API calls | CPA API Key |
GET /v1/models |
CPA API Key |
| CPAMP Manager Server APIs after setup | CPAMP Admin Key |
Do not mix these keys.
Common causes:
1. CPA usage publishing is not enabled
2. Manager Server is not configured
3. CPA URL is wrong from the Manager Server network perspective
4. CPA Management Key is wrong
5. CPA version is too old
6. Collector mode is incompatible with the network path
7. Multiple Manager Servers consume the same CPA usage queue
8. Manager Server was down longer than CPA queue retention
9. Poll interval is longer than the queue retention window
Check CPA usage publishing:
usage-statistics-enabled: trueOr enable it through CPA Management API:
curl -X PUT \
-H "Authorization: Bearer <CPA_MANAGEMENT_KEY>" \
-H "Content-Type: application/json" \
-d '{"value":true}' \
http://<cpa-address>:8317/v0/management/usage-statistics-enabledCheck Manager Server status:
curl -H "Authorization: Bearer <CPAMP_ADMIN_KEY>" \
http://<cpamp-host>:18317/statusImportant fields:
collector.lastError
lastConsumedAt
lastInsertedAt
eventCount
If lastConsumedAt is empty, Manager Server is not consuming events. Check CPA URL, Management API, CPA version, queue publishing, and collector errors.
If lastConsumedAt changes but lastInsertedAt does not, SQLite writes are failing. Check disk space, permissions, and /data mount.
If both change but the page is empty, check browser filters, time range, hard-refresh the page, and verify /v0/management/usage.
This usually means a RESP collector connected to an HTTP endpoint.
RESP mode must directly reach the CPA API port. It cannot pass through a normal HTTP reverse proxy.
Recommended fix:
USAGE_COLLECTOR_MODE=auto
Use CPA v6.10.8+ for the HTTP usage queue, or CPA v7.1.39+ for the current recommended metadata set.
If you must use RESP, set CPA URL to a direct address:
http://cli-proxy-api:8317
not a public HTTPS reverse proxy domain.
Inside a Docker container, 127.0.0.1 means the container itself.
If CPA runs on a Linux host and CPAMP runs in Docker:
docker run -d \
--name cpa-manager-plus \
--restart unless-stopped \
--add-host=host.docker.internal:host-gateway \
-p 18317:18317 \
-v cpa-manager-plus-data:/data \
seakee/cpa-manager-plus:latestThen use:
http://host.docker.internal:8317
Test from inside the container:
docker exec -it cpa-manager-plus sh
wget -qO- http://host.docker.internal:8317/healthzMost likely /data was not mounted, or Plus started with a new empty volume.
Correct:
-v cpa-manager-plus-data:/dataWrong:
docker run seakee/cpa-manager-plus:latestAfter migration from old CPA-Manager, be careful with volume names:
old common volume: cpa-manager-data
Plus examples: cpa-manager-plus-data
If you expect old data, mount the old volume or copy the old data.
Back up the full data directory:
usage.sqlite
usage.sqlite-wal
usage.sqlite-shm
data.key
data.key is required to decrypt the saved CPA Management Key. If it is lost, save the CPA connection again.
After setup, Manager Server endpoints require:
Authorization: Bearer <CPAMP_ADMIN_KEY>
Examples:
curl -H "Authorization: Bearer <CPAMP_ADMIN_KEY>" \
http://<cpamp-host>:18317/statuscurl -H "Authorization: Bearer <CPAMP_ADMIN_KEY>" \
http://<cpamp-host>:18317/v0/management/configThe CPA Management Key is not accepted for CPAMP Manager Server-only APIs.
Manager Server setup is not complete.
Open:
http://<cpamp-host>:18317/management.html
Finish setup first, then retry.
CPA usage queue is memory-backed and has limited retention.
Default retention:
60 seconds
Maximum:
3600 seconds
If Manager Server is down longer than the retention window, that period cannot usually be recovered from CPA. Keep Manager Server running continuously.
This is expected.
CPA panel mode does not use Manager Server analytics. Use:
http://<cpamp-host>:18317/management.html
for monitoring, dashboard analytics, model prices, API key aliases, usage import/export, and server inspection.
Read Reverse Proxy CPA and CPA Manager Plus with the Same Domain.
Rule of thumb:
/management.html -> CPAMP
/usage-service/* -> CPAMP
/v0/management/* -> CPAMP
/v1/* -> CPA
/backend-api/codex/* -> CPA
OAuth callbacks -> CPA
Fallback routes -> CPA
Use CPAMP Admin Key for CPAMP management paths and normal API keys for /v1/*.