# 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](/documentation/license).

## "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](/documentation/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](/documentation/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](/documentation/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](/documentation/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](/documentation/users-and-two-factor).

## 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

- [Security and Audit](/documentation/audit-and-security)
- [Configuration Reference](/documentation/configuration)

---
Source: https://selfdochub.com/documentation/troubleshooting
