Troubleshooting

This page lists common problems and how to resolve them.

Health checks and logs#

  • GET /healthz and GET /readyz return 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.

Next steps#

Last updated: