The Koha web installer returns a 500 error or times out

The web installer runs one long request per step, so a 500 or a gateway timeout means a step died or ran past Apache's limit — not that Koha is broken. Watch /var/log/koha/<instance>/intranet-error.log while you retry the step, raise Apache's Timeout if it is the long one, and only then consider starting the database again.

$ sudo tail -f /var/log/koha/library/intranet-error.log

Leave that running, then retry the installer step in the browser. The first new line is the fault. The generic 500 page carries no detail on purpose — reading the right log file covers what the common messages mean.

One or two steps — building the schema, loading the sample data — take minutes on a modest server. Apache gives up first and returns 504 while the step is still running underneath, which is why the timeout often "fixes itself" if you wait and reload.

Timeout 600

$ sudo apache2ctl configtest$ sudo systemctl reload apache2

Ten minutes is generous and temporary — put it back to the default (300) once the install is finished, because a long timeout on a live site keeps dead connections occupying workers.

The installer asks for a database user and password. They are generated when the instance is created — not chosen by you, and not the MySQL root password:

$ sudo koha-passwd library koha_libraryS3cr3tGenerated

Confirm those credentials actually work before blaming the installer:

$ sudo koha-mysql library -e "SELECT DATABASE(), CURRENT_USER();" DATABASE()	CURRENT_USER()koha_library	koha_library@localhost

If that fails, the problem is the database, not Koha. The full explanation of where these credentials come from is in finding your Koha instance's admin password.

When the schema step failed part-way, the supported reset is to remove the instance and create it again — it is a fresh install, so there is nothing to lose, and it is far more reliable than repairing a partial schema by hand.

$ sudo koha-remove library$ sudo koha-create --create-db library

Then reload the staff URL and the installer starts again from the first step.

The web installer is an ordinary CGI script doing a very unordinary amount of work: it creates every table, loads the mandatory data, and on request loads sample records — all inside a single HTTP request, with a browser waiting. Anything with a request deadline in front of it (Apache's Timeout, a reverse proxy, a load balancer) will eventually decide the request is dead.

That also explains the shape of most reports: the failure appears on the same one or two steps for everybody, it is worse on small virtual machines, and it goes away on a server with faster disk. It is not a sign that the install is going wrong in some deeper way.

The other frequent cause has nothing to do with time. If the environment is wrong — no configuration path, a database the user cannot reach — the very first step 500s immediately rather than hanging. An instant failure and a slow one are different problems, and the log tells them apart in one line. Start there, and see Koha cannot locate koha-conf.xml if the message names the configuration file.