Resources & Guides

Z39.50 Connection Troubleshooting: Diagnostic & Fix Guide

Fix Z39.50 connection problems in Koha. Troubleshoot timeouts, database errors, authentication issues, and network connectivity problems with step-by-step solutions.

11 min read

Z39.50 connection problems are usually easy to diagnose and fix. This guide covers the most common issues and their solutions.

Quick Diagnostic: How to Identify the Problem

When you click Test Connection in Koha and see an error, the message will typically tell you exactly what’s wrong:

Error Message Most Likely Cause Go To Section
“Timeout after X seconds” Server is slow or unreachable Timeout Issues
“Connection refused” Server/port is blocked or incorrect Connection Refused
“Database ‘X’ not found” Wrong database name in config Database Not Found
“Authentication failed” Wrong username/password Authentication Failed
“Unable to resolve hostname” Host address is misspelled or DNS issue Cannot Resolve Hostname
“Connection reset by peer” Network interruption or firewall Connection Reset
“Character encoding mismatch” MARC syntax or encoding setting incorrect Character Encoding

Timeout Issues

Error: “Timeout after 30 seconds” or “Timeout after X seconds”

What’s happening: Koha sent a request to the Z39.50 server but didn’t receive a response within the timeout window.

Causes & Fixes

1. Server is Temporarily Down

Check:

  • Try connecting to the server from your browser or a Z39.50 client on another machine
  • Check the Z39.50 Server Status Reports for recent issues

Solution:

  • Wait 15-30 minutes and test again
  • Try a different Z39.50 server (Library of Congress, OCLC) to confirm your Koha setup is working
  • If multiple servers timeout, see “Network Connectivity” section below

2. Timeout Value Too Low

Check:

  • What is your current timeout value? (See Z39.50 server config in Koha)

Solution:

  • Increase timeout from 30 seconds to 45-60 seconds:
    1. In Koha Administration → Z39.50/SRU servers
    2. Click Edit on your server configuration
    3. Change Timeout (Seconds) to 45 or 60
    4. Click Save
    5. Test connection again

When to increase timeout:

  • Connecting to servers outside your region (international servers are naturally slower)
  • Connecting during peak hours (library business hours)
  • Servers with large databases (OCLC WorldCat)

Recommendation: Start with 45 seconds for most servers; increase to 60+ only if needed.

3. Network Latency or Distance

Check:

  • Is this a geographically distant server? (E.g., Australian library accessing Japan server)
  • Are you on a slow internet connection?

Solution:

  • Increase timeout value (see above)
  • Try a closer server: Library of Congress (US-based, fastest for North America)
  • Check your network connection speed: ping lx2.loc.gov (should be <200ms)

4. Server is Overloaded

Check:

  • Try the same search at a different time of day
  • Check if other services on your network are running large downloads/backups

Solution:

  • Try a different time: Most library servers are slower 9am-5pm local time
  • Pause other network-heavy tasks (backups, large file transfers)
  • Increase timeout to allow the server more time to respond

Connection Refused

Error: “Connection refused” or “Unable to establish connection to X:210”

What’s happening: The Z39.50 server address or port is incorrect, or a firewall is blocking the connection.

Causes & Fixes

1. Wrong Host Address or Port

Check:

  • Is the hostname spelled correctly? (Typos are the #1 cause of “connection refused”)
  • Is the port correct? (Most use 210, but some use custom ports like 7090 or 9909)

Solution:

  1. Go back to Z39.50 Server Directory or add Z39.50 servers guide
  2. Copy and paste the exact hostname and port from the guide (do NOT type manually)
  3. Edit your server config in Koha
  4. Clear the incorrect host/port and paste the correct values
  5. Test connection again

Example: If your server shows lx2.loc.gov:210, enter:

  • Host: lx2.loc.gov (no port here)
  • Port: 210 (separate field)

2. Firewall Blocking Outbound Connections

Check:

  • Can you ping the server? Run: ping lx2.loc.gov (should show replies)
  • Is your Koha server behind a corporate firewall or restricted network?

Solution:

  • If ping works but Z39.50 fails: Firewall is blocking port 210 (Z39.50 protocol)
    • Contact your network administrator to allow outbound traffic on port 210 (or the server’s custom port)
    • Exception: Some servers use port 80 or 443 (HTTP/HTTPS) which are usually open
  • If ping fails: DNS or network issue (see Cannot Resolve Hostname)

For AWS/Cloud-hosted Koha:

  • Check your Security Group outbound rules allow port 210
  • Check EC2 Network ACL allows port 210
  • Run: telnet lx2.loc.gov 210 to test port connectivity

3. Server Address is Misspelled

Check:

  • Copy the hostname from server documentation or our directory
  • Look for common typos: extra spaces, missing dots, numbers vs. letters (O vs. 0, l vs. 1)

Solution:

Database Not Found

Error: “Database ‘X’ not found” or “Invalid database name”

What’s happening: The Z39.50 server is reachable, but the database name you specified doesn’t exist on that server.

Causes & Fixes

1. Wrong Database Name

Check:

  • Is the database name exact? (Case-sensitive on some servers)
  • Have you copied from our documentation?

Solution:

  1. Check Z39.50 Server Directory for the correct database name
  2. Common database names:
    • Library of Congress: LCDB
    • OCLC: OLUCWorldCat
    • British Library: BLAC
    • National Library of Australia: Voyager
  3. Edit your server config
  4. Clear the database field and paste the correct name
  5. Test connection again

2. Server Uses Different Database Name Than Expected

Check:

  • Different servers may use different names for similar content
  • Some servers have multiple databases

Solution:

  • Try alternate database names (check server documentation or our directory)
  • Use a different Z39.50 server if available (try Library of Congress as fallback)
  • Report the issue: Update Z39.50 Server Info

3. Server Moved or Renamed Database

Check:

  • Is this an older server configuration?
  • Check recent server update reports

Solution:

  • Report to our community: Z39.50 Server Updates
  • Try a different server temporarily
  • We’ll verify and update our directory

Authentication Failed

Error: “Authentication failed” or “Username/password incorrect”

What’s happening: The server requires login credentials (username/password) and what you provided is incorrect or missing.

Causes & Fixes

1. Wrong Username or Password

Check:

  • Are you using the correct institutional username/password?
  • Have credentials changed recently?

Solution:

  1. Verify your credentials with your library’s IT department
  2. Some servers use institution ID + password (e.g., OCLC)
  3. Edit your server config in Koha
  4. Enter the correct username and password
  5. Test connection again

Common credential patterns:

  • OCLC: Institution Symbol (e.g., ABC123) + password
  • LibLynx/IP proxy servers: Your library login
  • Consortium servers: Member institution ID + password

2. Authentication Not Required (Blank Fields OK)

Check:

  • Does the error say authentication failed, or are you unsure if you need credentials?

Solution:

  • If the server is public (Library of Congress, most academic libraries), leave Username and Password blank
  • Don’t enter anything, not even spaces
  • Test connection

3. Server Requires New Authentication Method

Check:

  • Is this an older server configuration that’s been updated?
  • Some servers migrated from username/password to OAuth or IP authentication

Solution:

Cannot Resolve Hostname

Error: “Unable to resolve hostname” or “Unknown host: X”

What’s happening: Your Koha server can’t find the Z39.50 server’s IP address using DNS (Domain Name System).

Causes & Fixes

1. Hostname is Misspelled

Check:

  • Did you type the hostname correctly?
  • Look for missing/extra characters: spaces, dots, letters

Solution:

  • Copy-paste the hostname from Z39.50 Server Directory instead of typing
  • Test with Library of Congress first: lx2.loc.gov

2. DNS Not Working on Koha Server

Check:

  • Run: nslookup lx2.loc.gov
  • Should return an IP address (e.g., 140.147.124.111)

Solution:

  • If nslookup fails: Your network doesn’t have DNS configured
  • Contact your network administrator to:
    • Add a DNS server (e.g., 8.8.8.8 for Google DNS, 1.1.1.1 for Cloudflare)
    • Verify internet connectivity
  • For AWS: Check Security Group DNS resolution settings

3. Temporary Network Outage

Check:

  • Try again in 5-10 minutes
  • Try pinging a different server: ping google.com

Solution:

  • Wait and retry
  • Check your internet connection
  • Verify network is stable

Connection Reset

Error: “Connection reset by peer” or “Connection closed unexpectedly”

What’s happening: The connection started but was interrupted by the server or a network issue.

Causes & Fixes

1. Network Interruption

Check:

  • Try connecting again immediately
  • Check for network outages or firewall rules

Solution:

  • This is usually temporary; try again
  • If persistent, contact your network administrator

2. Character Encoding Mismatch

Check:

  • Is your character encoding setting correct? (MARC-8 vs. UTF-8)

Solution:

  1. Edit your Z39.50 server config in Koha
  2. Check the Character Encoding field
  3. If unsure, try MARC-8 first (older, more compatible)
  4. If you see garbled characters, try UTF-8 instead
  5. Test connection

3. Server Configuration Incompatible with Koha

Check:

  • Are you using an older or custom Z39.50 server?
  • Check if your Koha version supports this server

Solution:

  • Try a different server to confirm your Koha setup works
  • Report issues: Server Update Form

Character Encoding Issues

Error: Text appears as garbled characters (例, ???, or mojibake)

What’s happening: The character encoding setting doesn’t match how the server sends data.

Causes & Fixes

1. Wrong Character Encoding Setting

Check:

  • What encoding did you choose? MARC-8, UTF-8, or other?

Solution:

  1. Edit your server config
  2. Try MARC-8 first (default for older records)
  3. If that shows garbled characters, try UTF-8 instead
  4. Test connection and import a record to verify
Encoding When to Use Best For
MARC-8 Default Older records, basic Latin characters
UTF-8 Modern Multilingual records, CJK (Chinese/Japanese/Korean)

2. MARC Record Syntax Mismatch

Check:

  • Is your MARC Record Syntax set correctly?

Solution:

  1. Most libraries use MARC21 (also called USMARC)
  2. European libraries may use UNIMARC
  3. Edit server config and verify the correct syntax
  4. Check Z39.50 Server Directory for each server’s syntax

3. Koha Installation Language Setting

Check:

  • Is your Koha interface set to a non-English language?

Solution:

  • This may affect how character encoding is displayed
  • Try switching Koha interface language to English temporarily to test
  • Or update character encoding to UTF-8 for better multilingual support

Server No Longer Responding

Error: Server worked before but now times out or refuses connection

What’s happening: The Z39.50 server may have moved, been updated, or is no longer available.

Causes & Fixes

1. Server Maintenance or Downtime

Check:

Solution:

  • Wait for server maintenance to complete
  • Try again in 1-2 hours
  • Use a different server in the meantime

2. Server Moved or Renamed

Check:

  • Check when you last tested this server
  • Look for server update announcements

Solution:

  1. Check Z39.50 Server Directory for updated connection info
  2. Delete the old server config in Koha
  3. Add new config with updated host/port/database
  4. Test connection
  5. Report outdated info: Server Update Form

3. Server No Longer Active

Check:

  • Is this an older or niche server?

Solution:

Getting Help

If these solutions don’t resolve your issue:

  1. Contact KohaSupport — We can help diagnose and fix Z39.50 connection problems. On KohaSupport Standard or Enterprise, Z39.50 configuration support is available directly — see plans
  2. Report a Server Issue - Help us update the server directory
  3. View Recent Server Updates - Check if other libraries reported similar issues

Next Steps

After Deployment
Post-Installation Setup
Recommended
Security Best Practices
Keep It Running
Monitoring & Maintenance

More in Resources & Guides

Was this article helpful?

Thanks for your feedback!