Koha cannot locate the configuration file koha-conf.xml

Nine times out of ten the file is exactly where it should be and the shell you ran the command in has no KOHA_CONF — Koha finds its configuration only through that variable. Run the command through sudo koha-shell <instance>, which sets it for you, and the error disappears without changing anything on disk.

$ perl /usr/share/koha/bin/some-script.pl CAUTION: Can't find koha-conf.xmlunable to locate Koha configuration file koha-conf.xml

It often arrives with a second, less helpful line — Can't call method "config" on an unblessed reference. That is the same fault one step later: the configuration object was never built, so the next line of Perl calls a method on nothing.

$ sudo koha-list library

Every instance is a directory under /etc/koha/sites/, and koha-list prints the ones that exist. Use that exact string below — koha, Koha and the library's name are the three things people guess, and none of them is it unless koha-list says so.

$ sudo koha-shell library$ perl /usr/share/koha/bin/some-script.pl

Replace library with your instance name. koha-shell drops you into a shell owned by that instance's system user with KOHA_CONF and PERL5LIB already exported, which is the supported way to run anything by hand. To run a single command without staying in the shell, use -c:

$ sudo koha-shell -c "perl /usr/share/koha/bin/some-script.pl" library

In a script that cannot call koha-shell — a systemd unit, someone else's wrapper — export the path directly. Nothing else reads it, so this is the whole fix:

$ export KOHA_CONF=/etc/koha/sites/library/koha-conf.xml$ export PERL5LIB=/usr/share/koha/lib

If the two steps above did not help, confirm the file exists before assuming anything else:

$ sudo ls -l /etc/koha/sites/library/koha-conf.xml -rw-r----- 1 library-koha library-koha 24596 Aug  9 11:02 /etc/koha/sites/library/koha-conf.xml

Note the ownership. The file is readable by the instance user and by root, and by nobody else — so the same command that works under sudo fails as an ordinary user with exactly this error, because Perl cannot open a file it is not allowed to read. That is the second most common cause after the unset variable.

Koha has no compiled-in configuration path. Every process discovers its instance from the KOHA_CONF environment variable, and that is deliberate: it is what lets one server run twenty instances from one copy of the code, each with its own database, ports and paths.

Each place Koha runs sets the variable in its own way. Apache sets it per virtual host — the site file contains SetEnv KOHA_CONF "/etc/koha/sites/library/koha-conf.xml" in both the OPAC and the staff blocks, which is why the web interface works perfectly while a command in a terminal does not. The scheduled jobs get it from koha-foreach. A root shell gets it from nowhere at all.

So the error is almost never about a missing file. It is a command being run outside the only three contexts that were ever arranged to set the variable, and koha-shell exists precisely to be a fourth.

If the staff interface itself is not answering rather than a script failing, the cause is on the Apache side instead — start with Koha, Apache and port 8080.