Gitea Not Working? Common Errors & Fixes
The 11 Gitea problems users hit most often, why they happen, and the fixes that actually work — collected from user reports, forums, and official support docs.
Gitea Actions Jobs Stuck in Waiting (No Matching Runner)
Workaround availableSelf-hosted, DockerJobs wait forever when no online runner has the label in runs-on. Match the label to a registered runner and confirm the runner is registered to your instance.
Gitea SSH Permission Denied (publickey) or Connection Refused
Workaround availableDocker, Linux, any clientUsually the wrong SSH port in the clone URL, the key not added to your account, or a username other than git. Test with ssh -vvv.
Gitea 500 Internal Server Error
Workaround availableSelf-hosted, Docker, HelmMost 500s trace to a ROOT_URL or LOCAL_ROOT_URL mismatch, a proxy that does not pass Host and X-Forwarded-Proto, or a failed upgrade. Check the Gitea log for the exact error first.
Gitea Reverse Proxy Wrong URLs or Redirect Loop (ROOT_URL)
Workaround availablenginx, Caddy, Traefik, Helm ingressSet ROOT_URL to the public URL and have the proxy pass the Host header and X-Forwarded-Proto. Subpath installs also need the subpath in ROOT_URL.
Gitea Push 413 Request Entity Too Large (LFS Upload Fails)
Workaround availablenginx, Cloudflare, DockerA 413 comes from nginx's body-size limit, Gitea's LFS_MAX_FILE_SIZE, or Cloudflare. Find which layer returns it, then raise that limit.
Gitea Webhook Not Working (ALLOWED_HOST_LIST Error)
Workaround availableSelf-hosted, Docker, HelmWebhooks to private IPs are blocked by default. Add the target to webhook ALLOWED_HOST_LIST in app.ini.
Gitea Email Notifications Not Sending (SMTP Error)
Workaround availableSelf-hostedEnable notification mail, then match the SMTP port to the right protocol: implicit TLS on 465, STARTTLS on 587.
Why Is Gitea Using So Much Memory or CPU?
OngoingSelf-hostedThe code indexer and repository mirroring are the usual culprits. Disable or move the indexer and check for version-specific regressions.
Gitea Upgrade Failed or Database Is Locked
Workaround availableSelf-hosted, Docker, TrueNAS, UnraidBack up, run gitea doctor, and move off SQLite if you see database is locked. Check that environment variables are not overriding app.ini.
Gitea Migration From GitHub Failed or Timed Out
Workaround availableSelf-hostedUse a valid token, handle GitHub rate limits and check server memory. A Failed status can still have copied files, so inspect before retrying.
How to Cancel Gitea Enterprise or Gitea Cloud
Workaround availableSelf-hosted, CloudGitea's free edition has nothing to cancel. Paid Enterprise and Cloud are arranged with Gitea, so cancellation goes through them; Enterprise online payment requires a 1-year commitment.
SANDBOX · gitea RUNS IN YOUR BROWSER
Try it: push, review, run CI and merge in a code host and cloud workspace
A hands-on Gitea-style sandbox, including the spots where users get stuck. 1-2 minutes, nothing is saved.
Problem not listed? See all Gitea complaints or compare Gitea alternatives.
// We build software. Any software.
Have an idea for an app? We'll build it.
We're a small team of developers who build custom software fast. Not just tools like Gitea: web and mobile apps, games, desktop software, AI tools, internal tools: whatever you have in mind. 50+ custom products built for clients so far, and we run our own products too: booking platforms, games, learning apps. See our work
- Web apps & SaaS
- Mobile apps (iOS & Android)
- Games
- Desktop software
- AI tools & automations
- Internal tools & dashboards
- Client portals & booking
- Your own version of any tool
- ✓ Free 15-min call to scope it
- ✓ Price agreed up front
- ✓ Your data, your code