Install & upgrade troubleshooting

Upgrade stops at

Upgrade stops at git fetch failed (would clobber existing tag)

Cause　This project's git history was rewritten on 2026-09-13 (to remove a piece of data that should never have been committed), so every tag now points at a new commit. While the local tags still point at the old ones, git fetch --tags (without --force) reports would clobber existing tag for each and exits with code 1.

What to do　Run this once and it is fixed for good (it only touches refs inside .git — your data is never touched):

Unaffected: tarball installs (no .git), the Windows installer, and anything installed after 2026-09-13. Fixed from v1.15.41.

Health check timed out (but the service is actually fine)

Symptom　The last step of the upgrade times out, yet the site opens in a browser.

Cause　After changing the listen address or port (jtdt bind), older versions read the address from the environment of the shell running the upgrade — where it was never set — so they always probed 127.0.0.1:8765. A corporate http_proxy can also send "connect to myself" through the proxy.

What to do　Fixed in v1.15.15 (it reads the service manager's own configuration, connects directly, and prints which addresses it probed plus the last 20 log lines). Upgrade to at least that version; if it still times out, read the end of jtdt logs.

CERTIFICATE_VERIFY_FAILED (corporate TLS inspection)

Symptom　Certificate verification fails during an upgrade, while downloading OCR language files, or when connecting to an LLM / SSO.

Cause　A corporate TLS-inspection proxy replaces external certificates with its own CA, which Python and uv do not trust by default.

What to do　The program hooks into the operating system's trust store automatically (truststore), so most environments need no configuration. If it still fails, import the corporate CA into the OS trust store; JTDT_TLS_INSECURE=1 bypasses verification temporarily (only on a network you trust).

An install without git cannot update

Symptom　jtdt update says git is missing, or that this is not a git repository.

Cause　Without git on the machine, the one-line installer falls back to downloading an archive, so the installation has no .git.

What to do　Install git and run the one-line installer again — it adopts the existing directory into a git repository (your .venv and data are kept), after which updates work normally.

Windows cannot find git, or asks you to install it with winget

Symptom　git was just installed but still cannot be found; or Windows Server has no winget.

Cause　A freshly installed program only updates PATH in the registry — terminals that are already open (including new tabs) still see the old one; and Windows Server 2019 / 2022 ship without winget.

What to do　Simply run it again — no reboot needed: the program looks in PATH, then the registry, then the standard install locations. On Server editions, download the installer from the git website.

[X] uv venv failed (when upgrading on Windows)

Symptom　Installing over an existing installation fails; a silent install appears to hang.

Cause　The service is still running and python.exe holds the virtual environment's files open, so they cannot be deleted. Older failure dialogs had no silent-mode default, so they waited for a button nobody could press.

What to do　Fixed in v1.15.37 (the service is stopped and its handles released before anything is deleted, and every dialog has a silent default). If it hangs, stop the service manually first; the installer's own log is at C:\ProgramData\jt-doc-tools\Logs\installer.log.

Not enough disk space during an upgrade

Symptom　The backup step fails — and the service has already been stopped.

Cause　Upgrades take a full backup of the data directory and keep three of them.

What to do　From v1.15.17 the space is checked before the service stops, and the message says how much is missing; the backup also skips anything that rebuilds itself (the company-ID database, temporary files, job results) — measured 1.93 → 0.56 GB per backup. Free up space and run it again.

attempt to write a readonly database

Symptom　After running a CLI command with sudo, the service can no longer write to the database.

Cause　Files created while running as root belong to root, while the service runs under its own account. The easiest one to hit is jtdt reset-password — the rescue command locks you out.

What to do　From v1.15.16 every CLI command restores ownership of the data directory when it finishes. On older versions, fix the ownership by hand (Linux: sudo chown -R jtdt:jtdt <data directory>).

Conversions return 503, or Chinese text comes out as empty boxes

Symptom　Office-related tools return "service temporarily unavailable"; or Chinese characters in the produced PDF are hollow boxes.

Cause　This machine is missing LibreOffice / OxOffice, or CJK fonts.

What to do　The error message names what to install. On Linux install libreoffice (or OxOffice) and fonts-noto-cjk; the admin area's "system dependencies" page lists exactly what is missing.

Remote users get "CSRF token missing or incorrect" as soon as they upload

Symptom　Everything works when tested on the server itself; only connections from another machine fail. Sign-in may also bounce back to the login page.

Cause　The reverse proxy sets X-Forwarded-Proto to a fixed https while the site is actually http — so the backend marks cookies Secure and the browser drops them over plain http. http://localhost is a secure-origin exception, which is why it cannot be reproduced on the server itself.

What to do　Make the reverse proxy pass the real protocol (on IIS, use a rewriteMap to translate {HTTPS} into https/http), or serve the site over HTTPS. Examples are in

Still stuck?

Attaching these makes it much faster:

• the operating system and version, plus the output of jtdt status
• jtdt logs of last 20 lines
• the complete output of the failing command (not just the last line — the real cause is often a few lines above)

Report an issue