Troubleshooting
This page lists common problems and how to resolve them.
Health checks and logs#
GET /healthzandGET /readyzreturn the basic liveness state. The Docker health check uses them, and so can an external uptime monitor.- Logs are structured JSON, one object per line, on stderr:
docker compose logs -f docs-hub.
Everything answers 402#
No valid license is installed or it has expired. The server log shows a license invalid warning with a renewal link. Open the License page as an administrator and upload a license. See License and Tiers.
"Issued for a different device_id"#
The license was issued for another installation. Run docs-hub --print-device-id against the same data directory the server uses and request a license for that ID. The device ID lives in the data directory, so keep it when you move or restore.
401 or the login screen appears again#
The session token is missing, expired or signed with a different session_secret. Sign in again.
A reader or editor sees no services#
They are not in a team that covers any service. An administrator must add them to a team. See Teams.
Publishing fails#
| Symptom | Cause |
|---|---|
401 |
Wrong or rotated service token. |
400 about format |
The service already has a different format. A service never mixes formats. |
info.title is required |
The document has no title and the service has no name yet. For GraphQL see GraphQL Schemas. |
413 from Nginx |
client_max_body_size is smaller than max_spec_bytes. |
402 with license_limit |
The service has more operations, methods or fields than your license allows. |
| Garbled YAML or GraphQL | curl -d strips newlines. Use --data-binary. |
A version does not become current#
Only versions on the service's main branch become current automatically. Check the branch name you publish to. See Versions and Branches.
Edits are refused with 409#
Someone else saved the same service structure, text page or parameter overlay since you opened it. Reload and apply your change again.
MCP client gets 404#
For security every rejected MCP request answers 404: a missing or unknown secret, a disabled token, an address outside the allowlist, or MCP not licensed. The audit log records the real reason as mcp_request_rejected. See MCP Server.
New MCP tools do not appear#
Refresh the tool list in your client after an upgrade: disable and enable the server or use its reload button. Tools such as list_branches and send_request also depend on the token's switches.
Copy buttons do not work#
Open SelfDocHub over HTTPS. Over plain HTTP the clipboard API is missing and the interface falls back to a legacy method.
Two-factor codes stopped working for everyone#
If session_secret was changed, existing authenticator secrets are unreadable. An administrator must reset each user's authenticator. See Users and Two-Factor Auth.
A page says the version was not found#
The address names a version that was deleted or removed by retention (history_depth). Choose another version in the breadcrumb dropdown.