What to look out for when upgrading to Koha 24.11
Last updated on: 29th May 2025| 6th May 2025 | Aude Charillon | Koha
Before your upgrade
1. Warn all library staff who use Koha of the upgrade date and times
We will have sent you information on how we run Koha upgrades; feel free to share it with your colleagues.
Koha will be unavailable while the upgrade is run. Staff should not attempt to login. If they do anyway and perform some actions, their changes may be lost once the upgrade completes.
During the upgrade, staff will need to record transactions manually – and add them to Koha afterwards.
Tip: to warn staff in advance, you can use a News item displayed solely in the staff interface.
2. Advise your library users
Your public catalogue will not be available during your Koha upgrade.
- If you use the Koha OPAC, we will enable the OPAC maintenance page. You can customize the contents of the page in advance by creating an HTML customization for the OpacMaintenanceNotice display location.
- If you use Aspen, the site will still be up but some user account functionality will be affected.
Tip: give some advance notice to your users by using a News item for the Koha OPAC or a system message for Aspen.
3. Check what’s new
With your upgrade, you will get all the new features and improvements from versions 24.05 and 24.11. To get some insights into what these are:
- Read our curated – but still extensive – list of new features.
- Watch some video highlights from our What’s On Our Mind series.
- Read about the new features documented in the Koha Manual so far.
4. If using BLDSS: run reports if you need to retain any data
When upgrading to Koha 24.11, the interlibrary loan module gets a bit of an architecture revamp in preparation for a bigger refurbishment. Because of this revamp, we will not be able to retain as part of your upgrade previous ILL requests made using the British Library on Demand service (Koha BLDSS backend). Any ILL requests using the BLDSS backend will disappear from your system. If you need to retain any BLDSS requests data, make sure you run reports and download the results prior to your upgrade.
Note: BLDSS has not been available via the British Library’s API since the cyber-attack the organisation suffered in October 2023.
After your upgrade
1. Check your workflows
Once we confirm your upgrade is complete, the most important thing to do is to check that everything is working as expected.
Our Koha upgrades page has a list of suggested things to check – 7 for the OPAC and 9 for the staff interface.
If you have added any custom CSS or JavaScript to your site (e.g., via OPACUserCSS / OPACUserJS and IntranetUserCSS / IntranetUserJS system preferences) we would advise you check how these are applied post-upgrade. If you have any custom integrations with local systems, it is best to check those still work correctly too.
- Log support tickets on our helpdesk if you find anything amiss.
2. Decide on label for the OPAC login form
If you use the Koha OPAC, be aware that the “Login” label on the OPAC login form is changing, for accessibility reasons (see our New OPAC preferences in Koha 24.11 blog post). After your upgrade, it will automatically become “Card number”.
- Use the OPACLoginLabelTextContent system preference to change it to “Card number or username” or “Username” if this is more appropriate for your library.
3. Set RESTAPIRenewalBranch
For services like Aspen Discovery or your library app, the connection with Koha is likely to be using the REST API.
Before 24.11, any item renewals passed to Koha via the REST API used the library of the API user account – a Koha user with specific permissions – as the library at which the transaction occured (stored in statistics.branch).
- To avoid your statistics being skewed towards that library, set the RESTAPIRenewalBranch system preference to a more appropriate value to be stored in the statistics.branch field for this type of renewals.
4. If using borrowers.lastseen: check the new option for TrackLastPatronActivityTriggers
Koha stores a “last seen date” (borrowers.lastseen) for each library member. This date gives an indication of activity on the user’s account, which is used by library teams for reporting and workflows.
The TrackLastPatronActivityTriggers system preference allows library teams to choose which actions update the last seen date. By default, the last seen date field is empty when the account is created – meaning some users could be missed from reports.
- If you want the last seen date to be filled when the user account is created, tick the new option ‘Creating a patron’ in the TrackLastPatronActivityTriggers system preference.
5. If linking to Koha reports: update your hyperlinks
To protect against CSRF (c
- If you use a “show report” link, change the suffix from /guided_reports.pl?reports=1&phase=Show SQL to /guided_reports.pl?id=1&op=show (where 1 is the report number).
- If you use a “run report” link, change the suffix from /guided_reports.pl?reports=1&phase=Run this report to /guided_reports.pl?id=1&op=run (where 1 is the report number).
6. If using ILLModuleCopyrightClearance: check HTML customization
The ILLModuleCopyrightClearance system preference has been moved to an HTML customization – display location: ILLModuleCopyrightClearance. If you had content in the system preference, it will have been moved to the HTML customization as part of your upgrade.
- Check your ILLModuleCopyrightClearance HTML customization and update formatting if required.
7. If using BlockExpiredPatronOpacActions: review options
Before 24.11, the BlockExpiredPatronOpacActions system preference was a on/off switch. When enabled, library members whose account had expired were blocked from both placing a reservation and renewing items. This behaviour is the same by default, but you can now pick and choose which actions to block.
- Review BlockExpiredPatronOpacActions and select options among the following: placing a hold on an item; placing an ILL request; renewing an item.
8. If using IntranetmainUserBlock: check HTML customization
The IntranetmainUserBlock system preference has been moved to an HTML customization – display location: IntranetmainUserblock. If you had content in the system preference, it will have been moved to the HTML customization as part of your upgrade.
- Check your IntranetmainUserblock HTML customization and update formatting if required.
9. If using freeform ILL backend in reports: update your SQL
The freeform ILL backend has been integrated into core Koha. From 24.11, this backend does not exist; it has been replaced by a default ‘standard’ form. If you are using freeform in your reports, no new requests will be returned in the results.
- If any of your reports filter on the freeform backend – e.g.,
illrequests.backend='freeform', update your SQL to filter on ‘standard’ – e.g.,illrequests.backend IN ('freeform', 'standard').
10. If selecting passwords in reports: update your SQL
Library members’ passwords are stored encrypted in the Koha database: you are not able to display an unencrypted password in a notice or see it using a report. From version 24.11, Koha reports that display any password fields are prevented from being run altogether.
- If you have reports with, e.g., borrowers.password or vendor_edi_accounts.password in the SELECT statement, remove this field.
- If you have reports selecting all fields –
SELECT *– from either the borrowers, deletedborrowers, borrower_modifications, smtp_servers, z3950servers, aqbookseller_interfaces or vendor_edi_accounts tables, update your SQL to specify each of the fields you need.
