Koha is powerful, but small configuration problems can stop important library work. A search may show no results. The OPAC may stop loading. Emails may stay in the queue. Staff may be unable to log in. These issues can feel stressful when circulation is active and patrons are waiting.
This Koha Troubleshooting guide is written for beginners. It explains common Koha problems in simple language and gives practical steps to find the cause without panic.
Start Here: The Beginner Koha Troubleshooting Checklist
Before changing settings, check the basics first. Many Koha problems come from simple causes like a stopped service, wrong URL, expired SSL certificate, full disk, or broken search index.
| Check | What to Do |
|---|---|
| Correct URL | Confirm staff and OPAC URLs are correct |
| Internet/server access | Check if the server is reachable |
| Disk space | Make sure the server is not full |
| Apache or web server | Confirm the web server is running |
| Database | Confirm MySQL or MariaDB is running |
| Memcached | Restart if sessions or performance feel unstable |
| Plack | Restart if staff interface acts strangely |
| Search index | Rebuild Zebra or check Elasticsearch |
| Cron jobs | Confirm notices, indexing, and cleanup jobs run |
| Recent changes | Check if an upgrade, restore, plugin, or setting caused the issue |
A good rule is simple: find the symptom, check the related service, read the logs, then make one change at a time.
How Koha Works Behind the Scenes
Koha is not only one website. It is a group of connected parts. The staff interface lets librarians work inside Koha. The OPAC lets patrons search the catalog. The database stores records, patrons, circulation, reports, settings, and notices.
Koha also depends on a web server, usually Apache, plus a database server such as MySQL or MariaDB. Search may use Zebra or Elasticsearch, depending on your setup. Koha also uses cron jobs and background services for indexing, overdue notices, cleanup, and email notifications.
When troubleshooting Koha, think in layers. A problem may look like a Koha issue, but the real cause may be Apache, the database, search indexing, cron jobs, email settings, or permissions.
Common Koha Problems and Quick Fix Table
Use this table as your first diagnostic map when something goes wrong.
| Problem | Likely Cause | First Fix |
|---|---|---|
| Staff interface not opening | Apache, DNS, SSL, or server issue | Restart web server and check URL |
| OPAC not loading | OPAC vhost or web server issue | Check Apache config and restart Apache |
| Login keeps failing | Wrong password, permission, IP restriction, or session issue | Check account, permission, and login settings |
| Search shows no results | Zebra or Elasticsearch index problem | Rebuild index |
| Emails not sending | SMTP or message queue issue | Check SMTP and cron jobs |
| Notices not generated | Cron jobs or notice triggers missing | Check overdue and advance notice setup |
| Upgrade error | Schema mismatch | Run schema upgrade after backup |
| Records visible in staff but not OPAC | OPAC suppression, item status, or indexing | Check item visibility and rebuild index |
| Koha is slow | Server load, large logs, database, search, or hosting limits | Check resources and logs |
| Restore works but search broken | Index not rebuilt | Rebuild Zebra or Elasticsearch index |
Problem 1: Koha Staff Interface Is Not Opening
If the staff interface is not opening, first check whether the server itself is reachable. Try opening the server IP or domain in the browser. If nothing loads, the issue may be DNS, hosting, SSL, firewall, or the web server.
Check Apache:
sudo systemctl status apache2Restart Apache:
sudo systemctl restart apache2If your Koha uses Plack, restart Plack too:
sudo koha-plack --restart libraryReplace library with your real Koha instance name.
If the staff page loads but shows an error, check Apache logs. On many Debian or Ubuntu systems, logs are stored under:
/var/log/apache2/A beginner mistake is changing several settings before reading logs. Logs usually show the real direction: permission issue, missing file, broken config, database connection problem, or Perl error.
Problem 2: Koha OPAC Is Not Loading
If the OPAC is not loading but the staff interface works, the issue may be related to the OPAC virtual host, port, domain, SSL, or OPAC-specific customization.
Check whether the OPAC URL is correct. Koha often uses different ports or subdomains for staff and OPAC.
Staff: library.example.org:8080
OPAC: library.example.orgRestart Apache:
sudo systemctl restart apache2If the OPAC loads with a broken layout, the issue may be custom CSS, JavaScript, theme settings, browser cache, or missing assets. Try opening the OPAC in a private browser window. If it works there, clear cache or check custom code.
Problem 3: Koha Login Problems
Login issues can come from wrong passwords, staff permissions, branch restrictions, session settings, IP-based restrictions, or browser problems.
First, confirm the staff username and password. Then check whether the staff account has permission to use the staff interface. A patron account is not always a staff account.
If staff are suddenly logged out again and again, check session settings and IP-related login restrictions. Some systems log users out when their IP address changes during the day.
Problem 4: Koha Search Shows No Results
Search problems are among the most common Koha troubleshooting issues. Sometimes records exist in the database, but OPAC and staff search show no results. This usually means the search index is missing, outdated, or misconfigured.
If your Koha uses Zebra, try a full rebuild:
sudo koha-rebuild-zebra -v -f libraryIf you restored a backup or migrated from another server, rebuilding the search index is especially important. Records can exist in the database while the search engine still has no updated index.
Also check the SearchEngine system preference. If your Koha uses Zebra, it should be set correctly. If your Koha uses Elasticsearch, the server-side Elasticsearch setup must also be working.
Do not switch from Zebra to Elasticsearch just by changing the preference. Elasticsearch needs server-side setup. If the backend is not installed or configured correctly, search can break.
Problem 5: Koha Records Exist but Do Not Appear in OPAC
Sometimes a record appears in the staff interface but not in the public catalog. That does not always mean the record is missing.
| Cause | What to Check |
|---|---|
| Record suppressed from OPAC | OPAC suppression settings |
| Item is withdrawn or lost | Item status |
| No item attached | Bibliographic record has no visible item |
| Branch visibility issue | Library or branch settings |
| Search index stale | Rebuild Zebra or Elasticsearch index |
| Custom OPAC rule | Local customization or plugin |
A good test is to open the record directly by biblionumber if possible. If the direct record page works but search does not, the problem is likely indexing. If the direct page also hides the record, the problem may be OPAC visibility or item status.
Problem 6: Koha Email Notices Are Not Sending
Koha email problems usually involve more than SMTP. Koha may need correct SMTP settings, notice templates, patron email addresses, message queue processing, and cron jobs.
For modern Koha, SMTP servers can usually be configured from:
More → Administration → Additional parameters → SMTP serversCheck these common email issues:
| Email Issue | What to Check |
|---|---|
| SMTP authentication failed | Username, password, app password, port, SSL/STARTTLS |
| Emails stay queued | process_message_queue.pl cron job |
| Overdue notices not created | Overdue notice/status triggers |
| Patron does not receive email | Patron email field and messaging preferences |
| All emails go to one inbox | SendAllEmailsTo still enabled |
| Email goes to spam | SPF, DKIM, DMARC, sender reputation |
The SendAllEmailsTo system preference is useful for testing because it redirects all outgoing messages to one email address. Do not leave it enabled in production, because real patrons may not receive their intended notices.
Problem 7: Koha Cron Jobs Are Not Running
Cron jobs are background tasks. They can create notices, process message queues, run cleanup, update search indexes, and create backups.
For package installs, Koha cron scripts are usually found under:
/usr/share/koha/bin/Common email-related cron scripts include:
| Script | Purpose |
|---|---|
advance_notices.pl | Creates advance and due notices |
overdue_notices.pl | Creates overdue notices |
process_message_queue.pl | Sends queued email and SMS messages |
If notices are not sending, do not only check SMTP. Check whether the notice was created and whether the message queue processor is running.
Problem 8: Koha Upgrade or Migration Problems
Koha upgrades can fail or behave strangely when the database schema does not match the installed Koha code. This is common after restoring an old database into a newer installation.
Use this command after a restore or upgrade when needed:
sudo koha-upgrade-schema libraryDo not run schema changes without a backup. Before every upgrade or migration, create a fresh backup and confirm you know how to restore it.
Problem 9: Koha Backup or Restore Problems
Backup and restore problems often happen because of a wrong instance name, missing config files, incomplete SQL import, wrong database name, or skipped search index rebuild.
For beginners, the safest flow is to first list the enabled Koha instances:
sudo koha-list --enabledThen back up the right instance. After restoring, run:
sudo koha-upgrade-schema library
sudo koha-rebuild-zebra -v -f library
sudo systemctl restart apache2
sudo systemctl restart memcachedIf your restore works but searches fail, rebuild the index. If the staff interface opens but data looks old, you may have restored the wrong database or imported the dump into the wrong instance.
Problem 10: Koha Is Slow
Koha performance issues can come from server limits, database size, old sessions, large logs, search index problems, slow disk, low memory, or overloaded hosting.
Check server resources:
df -h
free -m
topCheck whether the server disk is full. A full disk can break sessions, logs, database writes, indexing, and backups.
Also check logs and cron jobs. Too many old logs, failed jobs, or large uncleaned tables can affect performance. Regular maintenance matters for a stable Koha system.
Problem 11: Koha Permissions and Staff Access Problems
If a staff member cannot perform an action, the issue may be permission-related, not a broken Koha system.
Check the staff account permissions. A superlibrarian can do almost everything, but normal staff need specific permissions for cataloging, circulation, reports, tools, administration, acquisitions, and patrons.
Also check branch rules. Some Koha systems restrict staff from editing items, patrons, or holds from other libraries. For multi-branch libraries, permission problems can feel like software bugs. Always check user permissions and branch restrictions before changing server settings.
Problem 12: Koha Patron or Circulation Errors
Circulation errors usually come from rules, not server failure. If Koha refuses checkout, renewal, or hold placement, check the circulation rules first.
| Error Type | What to Check |
|---|---|
| Checkout blocked | Patron restriction, fines, item status, circulation rules |
| Renewal blocked | Renewal limit, due date, holds, item type rules |
| Hold not allowed | Hold policy, item type, branch, patron category |
| Wrong due date | Calendar, circulation rules, patron category |
| Fine not calculated | Fine rules, cron jobs, calendar, item type |
Do not change many rules at once. Test one patron category, one item type, and one branch at a time.
Where to Check Koha Logs
Logs help you see what changed and when. Koha has a Log viewer tool, and server logs can also help with deeper errors.
| Log Area | Use |
|---|---|
| Koha Log viewer | Staff actions, circulation actions, notice/template changes |
| Apache logs | Web server errors and page loading problems |
| Cron logs | Scheduled job problems |
| Koha action logs | System actions stored in database |
| Mail logs | SMTP and email sending issues |
In the staff interface, the Log viewer is usually found under:
Tools → Additional tools → Log viewerBeginner Command Reference for Koha Troubleshooting
Use these commands as a quick reference. Replace library with your real Koha instance name.
| Task | Command |
|---|---|
| List enabled Koha instances | sudo koha-list --enabled |
| Check Apache status | sudo systemctl status apache2 |
| Restart Apache | sudo systemctl restart apache2 |
| Restart memcached | sudo systemctl restart memcached |
| Restart Plack | sudo koha-plack --restart library |
| Rebuild Zebra index | sudo koha-rebuild-zebra -v -f library |
| Upgrade schema | sudo koha-upgrade-schema library |
| Check disk space | df -h |
| Check memory | free -m |
| View active processes | top |
Safe Troubleshooting Rules Before You Change Anything
Never troubleshoot a live Koha system carelessly. A small wrong change can affect circulation, patrons, catalog records, or notices.
| Rule | Why It Matters |
|---|---|
| Take a backup first | Protects data before risky changes |
| Write down the current error | Helps compare before and after |
| Change one thing at a time | Makes the real fix easier to identify |
| Test after each change | Prevents new hidden problems |
| Avoid production experiments | Protects live library work |
| Use official documentation | Reduces outdated-command risk |
| Keep screenshots or notes | Helps if support is needed |
If you are not sure what a command does, do not run it on production first.
When to Ask for Professional Koha Support
Beginners can fix many Koha issues, especially simple SMTP, Zebra, OPAC, cron, and permission problems. But some cases need expert support.
| Situation | Why Support Helps |
|---|---|
| Database restore failed | Risk of data loss |
| Upgrade broke staff interface | Version or schema issue may be complex |
| OPAC and staff both down | Could be Apache, database, Perl, SSL, or server |
| Patron data looks missing | High-risk data issue |
| Search engine migration failed | Zebra or Elasticsearch setup may need server work |
| Email sends to wrong users | Privacy risk |
| Backup is missing or corrupted | Recovery needs careful handling |
For libraries, reliable recovery matters more than guessing.
Need Help Fixing Koha Problems?
If your Koha staff interface, OPAC, search, email notices, backup, restore, migration, cron jobs, or Zebra indexing are not working properly, I can help you through my Koha services on Fiverr.
I provide beginner-friendly Koha support for troubleshooting, installation, email setup, backup and restore, migration, notices, indexing, and server configuration.Hire Me on Fiverr for Koha Support
Final Koha Troubleshooting Checklist
Use this quick checklist when something goes wrong.
| Step | Action |
|---|---|
| 1 | Write down the exact error |
| 2 | Check if the problem is staff, OPAC, search, email, login, or circulation |
| 3 | Confirm the server is reachable |
| 4 | Check Apache, database, memcached, and Plack |
| 5 | Check disk space and memory |
| 6 | Review recent changes |
| 7 | Read Koha and Apache logs |
| 8 | Rebuild search index if search is broken |
| 9 | Check cron jobs if notices or emails fail |
| 10 | Take a backup before major changes |
| 11 | Test after each fix |
| 12 | Ask for expert help if data is at risk |
Final Thoughts
A strong Koha Troubleshooting process starts with calm diagnosis. Do not guess. Check the symptom, identify the related Koha component, read the logs, and apply one fix at a time.
For beginners, the most common Koha issues usually involve search indexing, email cron jobs, Apache, permissions, OPAC settings, and upgrade or schema mismatches. Once you understand how these parts connect, Koha becomes much easier to maintain.
FAQs About Koha Troubleshooting
Start by identifying the exact symptom. Is the staff interface down, OPAC broken, search empty, email not sending, or login failing? Then check the related service, logs, and recent changes.
Koha search may fail because Zebra or Elasticsearch is not indexed correctly, the search engine setting is wrong, or the index is outdated after migration or restore. Rebuilding the index often fixes Zebra-based search issues.
The record may be suppressed from OPAC, attached items may be hidden, the item may be withdrawn or lost, or the search index may be outdated.
Common causes include wrong SMTP settings, missing app password, missing patron email, notices not configured, SendAllEmailsTo still active, or message queue cron jobs not running.
koha-upgrade-schema upgrades the Koha database schema for the selected instance. It is important after package upgrades, restores, and migrations where the database structure must match the installed Koha code.
For Debian package or standard installs, Koha cron scripts are usually under /usr/share/koha/bin/, although exact paths can vary by installation method.
One possible reason is IP or session behavior. If the user’s IP changes often, session restrictions may cause repeated logouts. Check session-related system preferences carefully.
Back up first, read logs, change one setting at a time, test after each change, and avoid running unknown commands on a live system.
Basic Koha troubleshooting is manageable if you follow a clear process. Server-level issues, failed upgrades, corrupted databases, and search engine migrations are more advanced.
