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.0

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