// troubleshooting guide · gitea
Gitea Upgrade Failed or Database Is Locked
- Status
- Workaround available
- platforms:
- Self-hosted, Docker, TrueNAS, Unraid
- updated:
- November 16, 2026
- reports:
- 3
- Method
- how we research
RUNBOOK · gitea/upgrade-failed-database-locked4 FIXES
// quick answer
Back up, run gitea doctor, and move off SQLite if you see database is locked. Check that environment variables are not overriding app.ini.
Most likely fix: Back up first
How to fix it
// try these in order, the most common fix is first
FIX 1Back up first
- 01Run gitea dump
- 02Copy app.ini and the database
Did this fix it?FIX 2Run doctor
- 01Run gitea doctor check --all --fix before and after upgrading
Did this fix it?FIX 3Move off SQLite
- 01Maintainers advise MySQL or PostgreSQL for database is locked errors
- 02Migrate the data and update [database] in app.ini
Did this fix it?FIX 4Check env overrides
- 01Look for GITEA__database__* variables in your container, which override app.ini
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
Gitea fails to start after upgrade, shows version errors, or logs database is locked.
Why it happens
- C-01Failed database migration
- C-02SQLite concurrency limits
- C-03GITEA__ environment variables overriding app.ini
- C-04Skipping backups
// this guide also covers
- gitea upgrade failed
- gitea database is locked
- gitea fails to start after update
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 500 Internal Server Error
- 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?