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. If the terminal is back at its prompt, dtxWiki has stopped; see Starting and stopping dtxWiki. |
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. |
| 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. Locally, stop the app before running the grant command. See the grant step. |
admin grant says the user does not exist | Sign up or create the account first, identify it by registered account email or use admin grant --user-id USER_UUID, 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. Open Account → User ID → Copy user ID and ask an Owner to add that UUID, or provide your registered account email. An IdP profile email is not necessarily an account email. Account creation alone does not grant membership. |
| Failed to load workspaces appears | The server did not return the workspace list within 30 seconds. Reload the page. If it keeps happening, the operator should check the app and its /health/ready response. |
| 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. |
| Ask or Agent is missing from the navigation | Both are experimental menus and hidden by default. Turn them on in Settings → Labs with Show Ask menu or Show Agent menu; see Turn on Ask. Copied Agent document links remain usable; browser Agent Search requires its Labs menu to be on. |
| An Ask link shows We couldn't find that page | Ask is turned off for your account in this browser. Turn on Show Ask menu, then open the link again. Turning Ask off deletes no Ask sessions or saved answers. |
| My Labs choices disappeared | The choices are saved for your account in one browser only. Another browser, device or browser profile, a private window, or cleared site data starts with both menus hidden. Owners and administrators cannot turn them on for you. |
| 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 | A browser-saved draft is visible to permitted workspace Editors and Owners, while Viewers see the published version. An MCP editing session remains author-private until submission. Check their role and the actual published version. 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 | Background processing handles imports. Locally it runs inside dtxwiki: check that the app is still running and look for job errors in its terminal. On a server, check the dtxwiki-worker service or the worker container. An operator can inspect Settings → Jobs if background work is not progressing. |
| An attachment has no Delete button, or deleting it fails | Only Editors and Owners delete attachments, and only files that are not in use: Unused files, or your own upload shown as In an open draft. Files In use or History only are protected. “Someone referenced or changed this attachment while the list was open. Refresh and try again.” or “Someone is using this attachment right now, so it cannot be deleted.” means that the file changed or is now in use, possibly in a draft you cannot see. Refresh the list and check its state. See Images, links, and citations. |
| Unused uploads are not removed automatically | An Owner may have turned off Unused file auto reclamation, or the retention period, counted from the upload time, has not passed yet. Removal happens in a later background cleanup run. Operators can look for the “context media orphan sweep” and “media blob gc” jobs in Settings → Jobs. |
| 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 | dtxWiki tries the browser clipboard and then an older copy method, so copying usually works over plain HTTP too. If the browser blocks both, dtxWiki selects the text where it can; copy it with Ctrl+C (⌘C on macOS). |
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. If sign-in shows Use 1–128 characters for the current password. for a password that used to work, that password is longer than 128 characters, which v0.1.2 allowed. It can no longer be used: reset it with Forgot your password? where email recovery is configured, or ask the server operator for a recovery link. 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 running background processing: dtxwiki itself on a local installation, or the worker service on a server. 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.
Starting and stopping dtxWiki
These messages appear in the terminal or log of dtxwiki. When dtxWiki cannot start, it prints an error and returns to the prompt. Read the last line first; if it ends in see the preceding error, the cause is printed just above it. npm users run the commands below as npx @dtxsuite/dtxwiki@0.2.1 ….
| Message or symptom | What to do |
|---|---|
Address/port already in use, followed by dtxWiki HTTP server could not start | Another program, possibly another dtxWiki, already listens on that port. dtxWiki has stopped again, including its background worker. Identify that process before starting another; stop it only if it is your intended installation. See running and stopping. |
dtxWiki is already running or storage is still active; stop the existing processes first | Another dtxWiki process still uses the same data directory or database, even on another port: another terminal, a background or service instance, a separately started worker, or a maintenance command. Find and stop it, then start again. After a forced stop, its leftover worker exits within about 10 seconds. Do not delete the .lock files in the data directory. |
A last line ending in could not start; see the preceding error | The real cause is printed above it, for example a configuration check or a refused database upgrade. Fix that cause and start again. For upgrade refusals, see Server checks for operators. |
dtxWiki initialization did not become ready before its deadline | Preparing the database took longer than 60 seconds, for example on the first start after upgrading a large database. dtxWiki stopped without applying an unfinished upgrade. Run dtxwiki bootstrap once in the same terminal; it has no time limit. Then start dtxwiki again. |
dtxWiki background worker did not become ready before its deadline | The background worker did not finish its startup checks within 60 seconds, and dtxWiki stopped. Read any error above the line and start dtxWiki again. If the message repeats, report it with the terminal output. |
dtxWiki background worker stopped unexpectedly (exit code N); dtxWiki has stopped | The background worker exited, so dtxWiki stopped with it. Read the error above this line, fix the cause, and start dtxwiki again. A failed import does not stop dtxWiki; it only marks that Library item as failed. |
A command stops with stop dtxWiki (server and worker) first: … | dtxwiki admin …, dtxwiki users …, dtxwiki bootstrap and input repairs need dtxWiki stopped. Press Ctrl+C in the terminal running dtxwiki, which also stops its worker, run the command, then start dtxwiki again. The refused command changed nothing. A dtxwiki-worker run started beside a running dtxWiki stops with the same message (exit code 4); close it, because dtxWiki already runs its own worker. Administrators can find other options in Run administration commands. |
managed runtime … | dtxWiki runs its own worker only with a regular local SQLite file. Use the default database, or run the worker yourself in external mode if you deliberately use another database configuration, such as PostgreSQL or a SQLite URI. |
runtime SQLite database must be a regular file without hard links | Both managed and external modes require a regular database file without hard links. Stop every app and worker using the database and verify a backup, then replace the file with an ordinary copy at the configured path. Preserve the file ownership and access permissions before starting again. |
Ask and search
If Ask is missing or an Ask link shows We couldn't find that page, turn on Show Ask menu in Settings → Labs; see Turn on Ask.
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. |
| Connection lost after a computer restart | A terminal’s export is temporary, and MCP registration can store only the variable name. Follow Save an environment variable and check for Configured in a new session without printing the key. |
| CLI connects but the VS Code extension fails | Check the extension’s own MCP configuration, then fully restart VS Code with the variable available. WSL extensions also need the variable in their Linux environment. |
token_workspace_denied | The credential does not allow the requested workspace, even if your account belongs to it. In Settings → MCP access, choose Edit workspaces on that access key or OAuth app, select the workspace, then choose Save workspaces. |
| 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. |
| “This setup recipe could not be rendered safely.” | The server's address uses plain HTTP with a hostname or a public address, or the chosen method needs HTTPS. Set up HTTPS, or for a trusted-LAN evaluation set DTXWIKI_PUBLIC_BASE_URL to the server's private IP address and use an access key. See LAN access. |
| 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. Then open Settings → MCP access → Connected MCP clients in that workspace and read the client's status. Credential expired needs a new access key or a new OAuth approval. Credential revoked means that the key or approval was revoked, this workspace was removed from it, or its holder is no longer a member. Use blocked needs an Owner to choose Reactivate. Check credential status appears when dtxWiki cannot tell which credential the client used (such a record is completed by the client's next call) or when that credential no longer exists; make one call from the client, or reconnect it. |
/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. |
validation_failed | An input exceeded a limit, such as a title over 256 characters, or contained unsupported characters. dtxWiki rejects such input rather than shortening it. Shorten the value and refresh the client's tool list. |
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. A trusted-LAN HTTP server can be checked the same way with --http http://192.168.1.20:21080/mcp; its TLS check then fails by design, so judge the connection by the [d] list_tools line.
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. A local installation keeps its own key in its data directory, so this status points to server configuration. |
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” | Another dtxWiki process still uses the data. Stop both writers before update, rollback, data migration, dtxwiki bootstrap or input repairs. systemd: sudo systemctl stop dtxwiki-worker dtxwiki; Docker: docker compose stop app worker; local: Ctrl+C in the terminal running dtxwiki. |
input restrictions preflight failed; use inputs audit and explicit UUID maintenance repairs before upgrading: … | Existing account names, emails, titles or similar values break the input rules that v0.2.1 enforces, so the upgrade was refused and nothing changed. Keep dtxWiki stopped and keep the backup. Run dtxwiki inputs audit, repair each listed ID, and repeat the audit until it exits with 0; then start again (with systemd, run sudo dtxwiki bootstrap before starting the services). Follow Upgrade from v0.1.2. Never stamp or delete the database. |
input audit refused: unsupported or inconsistent database | The audit could not inspect the configured database (exit code 2). Run it with the same settings and database as the server. A database that still records an old revision identifier needs revision conversion first. |
input repair refused: … or input repair failed: database conflict; no changes applied | The repair changed nothing. If the message asks you to stop dtxWiki, stop it first. Otherwise check the ID, field and value limits named in the message, then run the repair again. |
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. |
After going back to v0.1.2: DB version … > code version …, or migration_preflight_refused with unknown_revision | v0.1.2 cannot open a database that v0.2.1 has already upgraded. Do not rebuild or stamp it, even if the message suggests a rebuild. Start v0.2.1 again, or restore the backup taken before the upgrade together with v0.1.2. See Upgrade from v0.1.2. |
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. |
systemd: dtxwiki-worker keeps restarting with exit code 4, or the dtxwiki service reports that dtxWiki is already running, after a manual package upgrade | /etc/dtxwiki/dtxwiki.env lacks DTXWIKI_WORKER_MODE=external, so the app service started its own worker beside dtxwiki-worker. Stop both services, run sudo dtxwiki config set DTXWIKI_WORKER_MODE=external, then start both. Never add this setting for v0.1.2. |
systemd env-file discovery failed … or finalize-bootstrap refused: … during sudo dtxwiki update | The update stopped, and the services stay stopped. Keep them stopped and follow the message: run the command it prints with your env file, or fix the stated cause, then finish or roll back the update. See Upgrade from v0.1.2. |
unknown DTXWIKI_ env detected: DTXWIKI_WORKER_MODE | A v0.1.2 installation is reading configuration written for v0.2.1. Restore the env file backed up before the update, or remove that line. Do not switch to development mode to bypass the check. |
The health endpoint /health/live only says the process is alive. /health/ready checks readiness, including the database, app-version synchronization and the background worker. Its worker component is ok when dtxWiki runs its own worker, as a local dtxwiki does. systemd and Docker report n/a because their worker runs as a separate service that /health/ready does not check; check that service or container with the commands above. When Health in Settings → Deployment is not Ready, server administrators see each component there, including Background processing. 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.
Reference and citation problems
| Symptom | Check |
|---|---|
| Unresolved citation warning | Replace an old key or empty @cite{} using the editor's reference chooser and an accessible Context, Library or Agent document. |
| Reference changes do not save | Check the open version and latest editing revision. The combined reference limit is 500. After a conflict, reload and inspect the targets and notes before retrying. |
| No citation in the reader or graph | Publish the version containing the citation or registered reference. A saved draft and the current published version are different. |
| Public reference is unavailable | A target not authorized for an anonymous reader is shown as unavailable without its title. Only eligible Context pages can resolve for anonymous readers after their separate web-sharing decision; Library and Agent references remain unavailable on public pages. |
| A citation relationship has no retained evidence | A document relationship and retained version/artifact evidence are separate. An empty evidence panel alone does not invalidate the relationship. See graph evidence. |
MCP integrations send cite the version_id, latest expected_editing_revision, idempotency_key and explicit add/remove targets. The old claim-search input is unsupported. See reference authoring and API/MCP contracts.
Diagnose the new 0.2 workflows
| Symptom | Check |
|---|---|
| Knowledge Map link opens an unavailable page | Enable your account's Labs preference first, then ask an Owner to enable the workspace map. A server-wide disable overrides it. Map setup. |
| A known link or citation is missing from the graph | Publish the version containing the inline citation or registered reference, then check filters and the current published target. Saving an unpublished draft alone does not add a graph edge. Use link guidance. |
| Inbox has fewer items after refresh | Eligibility, claims, permissions and decisions can remove current-state notices. Reading is not a review decision. Inbox. |
| SSO asks to link an existing account | Sign in to that account and link explicitly. For an unverified-email conflict, use the offered admin request. Account. |
| A Context decision cannot be undone | The recorded result may have changed or the decision may be ineligible. Inspect History and the current published version. Review. |
| Old MCP integration fails after upgrade | Send explicit workspace_id, refresh tools/schemas, and handle compact results and omitted defaults. Contract 29. |
| Database is at the graph/Inbox merge but not the final head | Stop writers, preserve backups and follow audit/bootstrap/reproject. Do not force-stamp it. |
Version evidence: deployment troubleshooting and migration verdicts, start and stop messages, storage guards, input audit and repairs, readiness, Labs menus, MCP credential states, MCP tools and setup.