Gitea troubleshooting

Cannot clone or push (auth / 401 / permission denied)

HTTPS: password login may be disabled — use a personal access token as the password. Wrong username or expired token. SSH: public key not added to the user, wrong key in agent, or Gitea SSH on a non-22 port (use ~/.ssh/config Port). Deploy keys are read-only unless write access was granted. See Git and SSH labs.

Wrong clone URL / redirects after reverse proxy

ROOT_URL in app.ini must match the public URL (scheme, host, and port). Missing X-Forwarded-Proto / Host from nginx, Caddy, or Traefik causes http links or loop redirects. Restart Gitea after config changes. Check proxy labs: nginx, Caddy, Traefik.

Gitea won’t start / 502 from proxy

Process crashed — read journalctl -u gitea -e or container logs. Database unreachable (wrong DSN, Postgres down, SQLite locked or on full disk). Port bind conflict on 3000. Corrupt or unreadable app.ini. Confirm the binary listens: ss -tlnp | grep 3000.

Actions workflow never runs / stuck queued

Actions disabled in app.ini or for the repo. No runner registered, or runner offline. Job runs-on: labels do not match the runner’s labels. YAML under wrong path — Gitea scans both .gitea/workflows/ (native) and .github/workflows/ (compatibility); the file must be in one of those two directories. Syntax errors show in the Actions UI. Restart act_runner and check its log for registration or job pickup errors.

Runner offline / cannot register

Registration token expired or wrong instance URL. Runner must reach Gitea’s HTTP API (firewall, TLS, wrong ROOT_URL). Docker-based jobs need a working Docker socket or DinD on the runner host — see Docker lab. One runner executes one job at a time unless capacity is increased.

Webhook delivery failed

Target URL unreachable from the Gitea host (DNS, firewall, HTTP vs HTTPS). TLS certificate problems on the receiver. Secret mismatch on the consumer. Check Admin / repo → Webhooks → recent deliveries for status code and body. For local CI, ensure Gitea can resolve and connect to the hook endpoint.

Disk full / repos or LFS growing

Data path fills with bare repos, LFS objects, attachments, and Actions artifacts/logs. df -h and du -sh under APP_DATA_PATH. Prune unused LFS, delete old packages, and set retention for Actions. See disk volumes lab.

Migration / dump restore issues

gitea dump / restore must keep DB and file data in sync. Version skew between dump and binary causes migrate errors. After restore, fix ownership on the data directory (often user git) and verify RUN_USER in app.ini.

Debugging workflow

1. Service and listen port

systemctl status gitea
ss -tlnp | grep -E '3000|22'
journalctl -u gitea -n 100 --no-pager

2. Config and data paths

# Confirm ROOT_URL, DB type, APP_DATA_PATH
grep -E '^(ROOT_URL|APP_DATA_PATH)' /etc/gitea/app.ini
grep -A8 '^\[database\]' /etc/gitea/app.ini
df -h; du -sh /var/lib/gitea/* 2>/dev/null | sort -h

3. Actions runner

# UI: Site admin / repo → Actions → Runners
journalctl -u act_runner -n 100 --no-pager
# Or docker logs for the runner container

Practice scenarios

Hands-on Gitea scenarios on live Linux VMs: gitea

Cheatsheet →