// troubleshooting guide · gitea
Gitea 500 Internal Server Error
- Status
- Workaround available
- platforms:
- Self-hosted, Docker, Helm
- updated:
- November 16, 2026
- reports:
- 3
- Method
- how we research
RUNBOOK · gitea/500-internal-server-error4 FIXES
// quick answer
Most 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.
Most likely fix: Read the log
How to fix it
// try these in order, the most common fix is first
FIX 1Read the log
- 01Check Gitea's log output or journalctl -u gitea
- 02Note the exact error and version
Did this fix it?FIX 2Fix LOCAL_ROOT_URL for push errors
- 01In app.ini [server] set LOCAL_ROOT_URL = http://127.0.0.1:3000/ instead of localhost
- 02Restart Gitea and push again
Did this fix it?FIX 3Align ROOT_URL with the public URL
- 01Set ROOT_URL to the full public URL including scheme, host and port
- 02Restart Gitea
Did this fix it?FIX 4Run doctor after an upgrade
- 01Back up first with gitea dump
- 02Run gitea doctor check --all, then --fix if it reports problems
Did this fix it?
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. See where problems like this one start. 1-2 minutes, nothing is saved.
Symptoms
Pages or pushes return 500, pre-receive hook declined, or Internal Server Connection Error after an upgrade.
Why it happens
- C-01ROOT_URL scheme or host differs from the public URL
- C-02LOCAL_ROOT_URL set to localhost that does not resolve correctly
- C-03Proxy not forwarding Host and X-Forwarded-Proto
- C-04Incomplete database migration after upgrade
// this guide also covers
- gitea 500 internal server error
- gitea pre-receive hook declined
- gitea internal server connection error
Still not working?
If Gitea keeps failing, you're not alone. See every Gitea problem users report or the alternatives people switch to.
Have an app idea? Our small team builds any software: web and mobile apps, games, desktop, AI tools. Price agreed together.
Talk to usThe same problem in other apps
Other Gitea errors
- Gitea Actions Jobs Stuck in Waiting (No Matching Runner)
- Gitea SSH Permission Denied (publickey) or Connection Refused
- Gitea Reverse Proxy Wrong URLs or Redirect Loop (ROOT_URL)
- Gitea Push 413 Request Entity Too Large (LFS Upload Fails)
- Gitea Webhook Not Working (ALLOWED_HOST_LIST Error)
- Gitea Email Notifications Not Sending (SMTP Error)
- Why Is Gitea Using So Much Memory or CPU?
- Gitea Upgrade Failed or Database Is Locked