Troubleshooting
Start with the symptom you can see. If you need help, record the screen, approximate time, workspace name, and exact error text. Leave passwords, tokens, recovery URLs, and confidential content out of screenshots and reports.
Browser and workspace problems
| What you see | Try this |
|---|---|
| The local page cannot be reached | Keep the terminal running dtxwiki open. Use http://127.0.0.1:21080/ on the same computer. A remote installation needs its actual HTTPS domain. |
dtxwiki or uv is an unknown command | Finish the selected installation tool's PATH setup, then reopen the terminal. With uv, check uv --version, run uv tool update-shell if needed, and check dtxwiki --version. See first installation. |
| Address/port already in use | An app may already be running in another terminal or service. Identify that process before starting another; stop it only if it is your intended installation. See running and stopping. |
| Another device cannot use my local URL | 127.0.0.1 points to the device opening it. Use the server's LAN IP or actual HTTPS address; see LAN access. |
| Invalid/disallowed Host | Match the requested hostname/IP to the representative URL or DTXWIKI_ALLOWED_HOSTS. Listening on 0.0.0.0 alone does not allow every Host. |
| Settings → Deployment is missing | Workspace ownership and server-admin are separate. The operator must grant an existing account server-admin against the same database, then refresh the browser. See the grant step. |
admin grant says the user does not exist | Sign up or create the account first, confirm its exact login email, and use the same OS user and data/database environment as the app. |
| Sign up is unavailable | Shared servers close self-sign-up by default. Ask the server administrator for an account. |
| The shared workspace is missing | Check your signed-in account and workspace switcher. Ask an owner to add your exact login email. Account creation alone does not grant membership. |
| An edit/new button is missing | Your role or the page state may limit the action. Ask an owner to confirm your role; Viewer accounts do not have editing permissions. |
| A copied internal page link will not open | Sign in to the same server with a workspace member account. An internal link does not grant new access. |
| A public page cannot be opened | It may not have a published version, or web sharing may have been disabled. Ask the author; internal publication and publication to the web are different. |
| Changes are visible to me but not colleagues | Check whether they are still a private edit or draft. Saving an edit and publishing a reviewed version are different steps. See Context pages. |
| “Load more” appears | The list is paginated. Select Load more to see additional entries; the first screen is not the whole collection. |
| Image or file import is still processing | Check the source status and whether a same-version worker is running against the app's database. An operator can inspect Settings → Jobs if background work is not progressing. |
| Saving reports a conflict | Another edit may have changed the base. Keep your work, reload the current version, and follow the conflict/review flow rather than repeatedly overwriting it. |
| Copying a link fails | Use the offered text selection and copy manually. Automatic clipboard access may be blocked or require HTTPS. |
For a forgotten password, use the server’s recovery option if available; otherwise contact the server operator. Workspace owners do not automatically have account-recovery privileges. See Accounts and access.
SMTP is optional for ordinary signup and wiki use. Email verification and email recovery require mail configuration, a reachable representative HTTPS URL, and a running worker. A default local HTTP installation has no configured recovery-link mode. Configured mail status alone does not establish SMTP authentication or delivery to an inbox.
Ask and search
An evidence list without a generated prose answer can be normal: an LLM provider is optional and off by default. Review the evidence and citations. An AI app connected by MCP does not automatically enable dtxWiki’s own Ask composer.
If search is empty, confirm that the content is in the current workspace, that you can read it, and that the relevant source has completed processing. Try an exact title or a distinctive keyword. Semantic search requires a configured embedding provider; keyword and navigational search work without one. See Search and Ask.
AI connection problems
| Symptom or code | Meaning and action |
|---|---|
401 when opening /mcp directly | Normal without credentials. Configure the client with a PAT or complete OAuth approval. An expired or revoked credential can also cause authentication failure. |
token_workspace_denied | The credential does not allow the requested workspace, even if your account belongs to it. Edit that connection’s allowed workspaces in Settings → MCP access. |
| A write is denied | Check both membership role and credential scopes. A read-only key or Viewer membership cannot authorize writing. |
| OAuth is unavailable | The server needs an HTTPS issuer. Plain HTTP evaluation uses an access key. With an internal CA, install trust for the CA in the browser and client. |
| The connection appears in settings but a tool fails | Registration and a successful tool call are different checks. First ask the client to list accessible workspaces and read one known page. |
/mcp returns the landing HTML | The reverse proxy is routing MCP to the web app fallback. Ask the operator to check /mcp routing. |
unknown_tool | The requested name is not in the server's current tool list. Refresh the client's tool list and remove unrecognized tool names from saved instructions. |
grant_replica_missing | Workspace access is being synchronized. The worker retries reconciliation. If it persists, the operator should check failed jobs. |
workspace_plane_unavailable | Storage access for the requested workspace is unavailable. The operator should check storage and connectivity. |
The optional helper can check the server independently:
dtxwiki mcp doctor \
--http https://wiki.example.com/mcp \
--token-env DTXWIKI_MCP_PAT
Set DTXWIKI_MCP_PAT securely in the environment before using the example. The check covers server authentication discovery and, with a PAT, tool listing. It does not prove that your particular AI app has completed its own connection. Follow Connect an AI app.
Server checks for operators
For systemd:
sudo systemctl --no-pager --full status dtxwiki dtxwiki-worker caddy
sudo journalctl -u dtxwiki -n 50 --no-pager
sudo journalctl -u dtxwiki-worker -n 50 --no-pager
curl -fsS https://wiki.example.com/health/ready
For Docker, run docker compose ps and docker compose logs --tail=50 app worker from the existing production Compose directory. Review and redact log output before sharing it.
| Startup or maintenance error | Next step |
|---|---|
| Session secret or production configuration guard | Read the specific hint, confirm the production environment, and correct it using the supported CLI. Do not disable the guard. |
oauth_jwk=ephemeral_unsafe | The production OAuth signing-key path is missing or invalid. Check the persistent key path, file ownership, and permissions. Ordinary restarts should not generate new keys. |
app_version=unsynced or bootstrap required | Stop app and worker, back up any existing data, then run sudo dtxwiki bootstrap through the production wrapper. Start services only after it succeeds. |
| “stop dtxWiki (server and worker) first” | Stop both writers before update/rollback/data migration. systemd: sudo systemctl stop dtxwiki-worker dtxwiki; Docker: docker compose stop app worker. |
migration_preflight_refused | Preserve the original database and record the full error. Verify the configured data path and backup before changing anything; follow Backups and maintenance. Never blindly stamp or delete the database. |
Existing revision 0001_initial_release or 0002_epic1 is refused | A reused database may need the explicit identifier conversion. Keep writers stopped and follow Convert existing revision identifiers, including backup, configured-database checks, and preview before --apply. Fresh installations do not need it. |
revision_rename_refused | The conversion could not verify a supported schema/revision. Preserve the database and backup and ask the operator to inspect the exact error. Do not force a stamp or recreate the database over it. |
unversioned_populated, partial_schema, stamp_marker_conflict, invalid_alembic_revision, or probe_error | The file/path/schema is not proven safe to migrate. Confirm the configured database and backup; restore a complete valid backup or plan a separate verified reconstruction. |
The health endpoint /health/live only says the process is alive. /health/ready checks readiness, including the database and app-version synchronization. A successful health check should be followed by browser sign-in and a content read when validating a deployment.
Ask for help or report a problem
For a shared-server account, workspace, or deployment problem, contact your server administrator first. They can check the actual installation and logs. For a reproducible product bug or a feature request, use dtxWiki GitHub issues.
Include the installed dtxWiki version, installation method, operating system, browser or AI client version, steps to reproduce, expected result, and the exact error or request ID. Use fictional sample content and a redacted screenshot when useful. Leave tokens, passwords, recovery links, private documents, and configuration secrets out of public reports.
For a suspected security vulnerability, report privately. Follow the security reporting policy: use the repository's Security → Report a vulnerability option or email dtxwiki.ai@gmail.com. Include the affected version, deployment method, reproduction steps, and observed impact without real credentials or personal data.
Version evidence: deployment troubleshooting and migration verdicts, MCP tools and setup.