Migration & upgrades
Koha keeps asking to update the database after an upgrade
The web installer comes back on every login because one update step failed and Koha stopped there. Run the update from the shell, read the ERROR line, fix that one thing, and run it again.
By Babar Junaid
Published 2026-11-12 · Tested against Koha 26.05
If Web installer › Update database comes back after every login, one step of the upgrade failed and Koha stopped there. The database version stays below the program version, so every staff page sends you to the installer and the OPAC shows its maintenance page. Run sudo koha-upgrade-schema library, read the ERROR: line, fix that one problem and run it again.
Take a backup before you run the update again
sudo koha-dump librarywrites the database and the configuration to/var/spool/koha/library/.- Copy that file off the server before you change anything.
Step 1: Run the update from the shell and read the error
The button in the browser runs the same steps, but when one fails the page only shows Update errors : and a Try again button that brings you back to the same screen. The shell prints all of it:
$ sudo koha-upgrade-schema libraryUpgrading database schema for libraryUpgrade to 26.05.02.002 [06:36:08]: Bug 42988 - Set holds_get_captured default to 1 in sip_accounts ERROR: {UNKNOWN}: DBI Exception: DBD::mysql::db do failed: Unknown column 'holds_get_captured' in 'WHERE' at /usr/share/koha/lib/C4/Installer.pm line 818Response from a live run on Koha 26.05 on a fresh Ubuntu 24.04 server
Replace library with your instance name (sudo koha-list prints it). This run failed on purpose: we removed a column that update 26.05.02.002 needs. Your step number, bug and message will differ. What matters is the last Upgrade to line and the ERROR: line indented under it, which a terminal shows in red. The command exits with status 1 and stops there; every step before it is already applied and will not run again.
Do not look for the browser's attempt in a log file. The installer creates updatedatabase_… and updatedatabase-error_… files while it runs and deletes them again, because on Koha 26.05 the update runs inside the page and writes nothing to them. The error exists only on the page and in the command's output:
$ sudo ls -t /var/log/koha/library/updatedatabase*ls: cannot access '/var/log/koha/library/updatedatabase*': No such file or directoryResponse from a live run on Koha 26.05 on a fresh Ubuntu 24.04 server
Step 2: Fix the one thing the error names
The error is nearly always about your data or your database server, not about Koha. The usual ones:
| Error text contains | What it means and what to do |
|---|---|
Duplicate entry … for key | The step adds a unique key and two rows break it. Find the duplicates with a SELECT … GROUP BY … HAVING COUNT(*) > 1 on the named column, merge or correct them, then run the update again. |
Cannot add or update a child row: a foreign key constraint fails | Rows point at something that no longer exists (an item at a deleted branch, a patron in a deleted category). Fix or remove the orphan rows the step names. |
Incorrect … value: '0000-00-00' or Data truncated | Old data that a strict SQL mode refuses. Correct the values in the named column; do not switch strict mode off to get past it. |
Row size too large | Old tables still on the COMPACT row format. Convert the named table with ALTER TABLE … ROW_FORMAT=DYNAMIC. |
Access denied or command denied | The database user in koha-conf.xml lacks ALTER or REFERENCES rights on the Koha database. |
Do not set the Version preference by hand
Version row in systempreferences makes the installer go away, but the steps after the failed one never run. Koha then runs against a database missing columns it expects, and the errors turn up weeks later on unrelated screens.Step 3: Run it again and check the version
$ sudo koha-upgrade-schema libraryUpgrading database schema for libraryUpgrade to 26.05.02.002 [06:36:24]: Bug 42988 - Set holds_get_captured default to 1 in sip_accounts Set holds_get_captured to 1 for 0 sip_accounts rows where it was NULL Changed default of 'holds_get_captured' in sip_accounts to 1Upgrade to 26.05.03.000 [06:36:24]: Koha 26.05.03 releaseUpgrade to 26.05.04.000 [06:36:24]: Koha 26.05.04 release…Upgrade to 26.05.05.000 [06:36:24]: Koha 26.05.05 release$ sudo koha-upgrade-schema libraryUpgrading database schema for libraryNo database change requiredResponse from a live run on Koha 26.05 on a fresh Ubuntu 24.04 server
With the cause fixed, the failed step runs, followed by every step after it, each with its notes indented underneath. Notes in yellow, such as 'LibrisKey' syspref already removed, are information, not errors. Run it again until there is no ERROR: line; a run with nothing left to apply prints No database change required and exits 0. Then restart the caches so no worker keeps the old version in memory:
$ sudo systemctl restart memcached$ sudo koha-plack --restart library * Stopping Plack daemon for library [ OK ] * Starting Plack daemon for library [ OK ]Response from a live run on Koha 26.05 on a fresh Ubuntu 24.04 server
The memcached restart prints nothing. On a terminal each Plack line ends in [ OK ]; in a script or a cron job the same lines end in ...done. instead. Leave out the Plack line if Plack is not enabled on the instance. Log in again: the staff interface opens without the installer, and the OPAC is back.
Why this happens
Koha keeps its database version in the Version system preference and compares it with the version of the installed code on every page. While the database is behind, the staff interface sends you to the web installer and the OPAC to its maintenance page. That check is what stops Koha from running new code against an old schema.
An upgrade is a list of numbered steps. Koha applies them in order and moves Version forward only after each one succeeds. On the first failure it stops, deliberately, because later steps often depend on earlier ones. So the version stays just below the failed step. Clicking Update your database again re-runs the same step against the same data and fails the same way. That is the loop.
On a package install, apt upgrade already ran this command for you, and its output went past in the package log. The error has been there since the upgrade; the browser is only the first place you noticed it.
Troubleshooting
| What you see | Cause |
|---|---|
| The OPAC shows a maintenance page, staff see the installer | Normal while the database is behind. Both clear once the update completes |
No database change required, or Everything went okay. Update done., but the installer still appears | Plack and memcached still hold the old version number. Restart both (step 3). This is the loop most people hit when Plack is on |
| Update errors : and Try again brings back the same page | One step failed. Read its error with koha-upgrade-schema in the shell (step 1); no log file keeps it. On a git or hand-copied install, check the update files under installer/data/mysql/db_revs/ are all there and readable |
| The update button times out in the browser | A long step. Run it from the shell instead, where nothing times out |
| The installer asks for the database password or to install from scratch | Koha cannot read its configuration. See Koha cannot locate koha-conf.xml |
| 500 errors on every page after the update finished | Read the log line, as in finding the line behind a Koha 500 error |
Before the next upgrade, back up with koha-dump and keep the copy somewhere other than the server. The whole upgrade, with its rollback, is in upgrading Koha step by step.
Tested on live Koha 26.05.05
Passed all 14 checks · Read the run log
- Koha release
- 26.05.05
- System
- Ubuntu 24.04
- Setup
- A fresh Ubuntu 24.04 server reached over SSH as a sudo user, Koha installed from the Koha repository as our installation guide leaves it.
- Source read at
- Koha commit d3fc229
Earlier live checks (1)
- , Koha 26.05.05 (commit d3fc229): all 18 claims held. Read the run log
In the Koha manual (26.05)
Verified against the Koha source (6 files)
- C4/Auth.pm (lines 760-805)
- koha-tmpl/intranet-tmpl/prog/en/modules/installer/step3.tt (lines 322-334, 413-472)
- installer/install.pl (lines 395-420)
- C4/Installer.pm (lines 847-898, 1044)
- debian/scripts/koha-upgrade-schema
- debian/koha-common.postinst (lines 23, 293-294)
The label under each command says where its response came from; a command with no label was not run live. How we test and which standards we follow.
Upgrade stuck halfway? Send us the ERROR line and we will finish it on your server, with a backup taken first.

