Troubleshooting¶
"I cannot sign in"¶
admin / admin is refused on a fresh install. Someone has already signed in
and changed it — Prodpeek forces a change on first login and the old password
stops working there and then. Reset it:
docker exec prodpeek python -c "
from prodpeek.app import create_app
from prodpeek.config import Config
store = create_app(Config.from_env()).state.gateway.store
user = store.get_user_by_name('admin')
store.set_password(user.id, 'a-new-password')
print('reset')
"
The login page loads but the password never works, and you just enabled TLS.
Check PRODPEEK_SESSION_HTTPS_ONLY. With it on and no TLS actually in front, the
session cookie is marked Secure, the browser will not send it back over plain
HTTP, and you land on the login page again with no error. Either put TLS in front
or turn it off.
429 on the login page. The rate limit: 10 attempts per 5 minutes per address.
Wait, or raise PRODPEEK_LOGIN_MAX_ATTEMPTS.
"My key stopped working"¶
Check the audit log first — this is answerable rather than guessable.
| In the log | Means |
|---|---|
token_expired |
The TTL ran out. Mint another |
wrong_door |
A client key at /api/v1, or an admin key at /mcp |
| nothing at all | The key was never known — revoked, or a typo |
"The agent says everything is denied"¶
Check what the key actually holds. Have the agent call prodpeek__explain, or:
A key grants specific services. A granted name that is not configured, or lives in another project, is inert — grants intersect with live state rather than adding to it.
Check the service has a credential. prodpeek service list shows !! for any
service still awaiting one. A service in awaiting_credential has an outstanding
drop link nobody opened.
Check the profile. prodpeek profile show coolify/read-only lists every
verdict. If the tool the agent wants is denied, that is the policy working — and
the note says why.
"Test connection shows tools under 'advertised but absent from the policy'"¶
That is deny-by-default being visible, and it is not an error. The vendor exposes a tool nobody has classified, so it is refused.
A long list usually means the profile was drafted against a different version of the vendor's server. Open an issue on prodpeek/profiles with the list — it gets corrected rather than quietly allowed.
"Test connection fails but the credential is right"¶
| Symptom | Usually |
|---|---|
upstream_unreachable |
Prodpeek cannot reach the host. Check the network from inside the container: docker exec prodpeek python -c "import httpx; print(httpx.get('https://...').status_code)" |
did not return JSON |
The URL points at a dashboard rather than an API root. Coolify's MCP endpoint is /mcp; Prometheus wants the base URL, not /graph |
redirected (301) |
Redirects are not followed, on purpose. Point at the final URL — usually https:// rather than http:// |
401 / 403 |
The credential is wrong, expired, or lacks the scope. Re-read that service's page |
"Prometheus returns nothing"¶
Check the targets first. prometheus__targets answers "is Prometheus actually
scraping that box", which is the question behind most empty graphs.
A 31-day ceiling and a 15-second step floor are built in. A range query outside those is refused with a clear message rather than making Prometheus slow.
prometheus__config is denied on purpose. prometheus.yml contains the
credentials Prometheus scrapes with. Read it yourself; it is not secret from you.
"prove says 'attention'"¶
Read the sentence — it says which check could not be made.
toolset not checked — X did not answer |
The upstream was unreachable during the run. Not a gate failure |
credential scope not established |
The vendor exposes no introspection. Honest, not broken |
credential CAN WRITE on X |
Go and look. The vendor says your credential can write; re-read that service's page |
AUDIT CHAIN BROKEN |
Records at and after the break can no longer be trusted as written. Investigate |
"The wall held" and "fully proven" are separate. An unreachable upstream fails the second and says nothing about the first.
"The container will not start"¶
PRODPEEK_SECRET_KEY is not set |
Generate one with prodpeek gen-key |
InvalidToken on boot |
The secret key does not match the one that encrypted this data volume. Restore the right key — the credentials cannot be decrypted without it |
Permission errors on /data |
On a Linux host with a bind mount: sudo chown -R 10001:10001 ./data |
Reading the audit log directly¶
docker exec prodpeek cat /data/audit.jsonl | tail -20 | python3 -m json.tool
docker exec prodpeek prodpeek audit-verify
Audit → Denials in the console groups every refusal by tool and reason. A pile on one tool means either an agent trying something it should not, or a profile missing a read people genuinely need. That view is the actionable half of the log.
Still stuck¶
Open an issue at prodpeek/prodpeek with the output of:
Neither contains a credential.