Skip to content
gtcnsl
Docs Source
EN RU

Troubleshooting & FAQ

Most problems are one command away from a diagnosis. Start with doctor, read the right log, and check the common cases below.

Updated for v1.3.2

Start with doctor

gtcnsl doctor          # PASS / WARN / FAIL per check
gtcnsl doctor --fix --yes

doctor probes systemd, outbound HTTPS, disk, privileges, the binaries, app.ini, secrets, and unit state. --fix attempts known remediations (install ca-certificates, generate a missing secrets.ini) then re-runs.

Exit codes & logs

  • Exit 0 — success (warnings still count as success for doctor).
  • Exit 1 — the operation failed, or doctor found a FAIL.
  • Gitea logs: /var/log/gitea/. gtcnsl state (backups, schema cache, self-update snapshots): /var/lib/gtcnsl/.
  • Service logs: journalctl -u gitea and journalctl -u gitea-runner.

Common cases

[!NOTE] gtcnsl: command not found The binary is at /usr/local/bin/gtcnsl but your shell hasn't picked up /usr/local/bin yet — open a new session, or call it by full path once.

!
Runner registration fails
The instance domain must resolve to the host first, and registration tokens are usually single-use. Point DNS, grab a fresh token from Gitea's settings, and re-run gtcnsl runner register --instance … --token ….
i
A config change rolled itself back
config apply/set/toggle restart Gitea and health-check it; if it doesn't come back, gtcnsl restores app.ini.bak and restarts again. Read journalctl -u gitea to see why Gitea rejected the change, fix the template, and re-apply with --dry-run first.
i
CI jobs never start
Confirm the runner is registered and active (gtcnsl doctor, systemctl status gitea-runner) and that your workflow's runs-on labels match the ones you registered with (--labels).
!
HTTPS / certificate errors
A fresh box may lack CA certificates. gtcnsl doctor --fix --yes installs ca-certificates and re-checks reachability to dl.gitea.com.
!
SSH pushes fail with "Internal Server Connection Error" after upgrading to Gitea 1.27+
gitea serv (spawned per SSH request) calls Gitea's internal API through [server] LOCAL_ROOT_URL. Left unset it defaults to https://localhost:<port>/; on an https-acme or https-manual install the certificate is bound to the real domain, not localhost, so that internal TLS handshake fails — look for no certificate available for 'localhost' in journalctl -u gitea. Gitea 1.26 tolerated the mismatch; 1.27 tightened the internal TLS path. Fix: gtcnsl config set server.LOCAL_ROOT_URL <your ROOT_URL> --yes (e.g. https://git.example.com/). Fresh https installs and gitea enable-https set this automatically going forward; gtcnsl doctor warns about it on installs made before this fix.
i
An empty or stale download
Verify what you pulled against the signed checksums.txt (see Installation). gtcnsl's own self-update verifies SHA-256 automatically and rolls back on mismatch.

Still stuck?

Open the contact page and send the failing command plus the relevant journalctl lines — that's almost always enough to pin it down.