Troubleshooting Common Problems

This is a general list of issues to check when troubleshooting problems with proxying databases. You should try each suggestion in order, and after making each change, perform the Retest Procedure.

Retest Procedure

After making each of the changes suggested below, you will need to retest. Each time you retest, you should:

  1. Close all browser windows
  2. Relaunch your browser
  3. Clear your browser cache
  4. Connect to the database and retest

0. First place to look: messages.txt/ezproxy.msg

If EZproxy is noticing any issues, it will record error messages to the messages.txt/ezproxy.msg file. If anything is wrong, the first place you should check is toward the end of this file. If you are able to log into EZproxy, you should be able to use the information at EZproxy Administration to create an administrative account and log into your EZproxy administration page where there are options to view this file. If you cannot access the administration page, you can view this file with a text editor or on Linux and Solaris with the tail command.

1. "Page not found," "Cannot find server or DNS," or remote browser waits and waits

When users receive these errors in their browsers, it normally indicates to firewall or DNS issues.

1.a. Proxy by port has worked for awhile, but gives this error to all remote users for certain databases, particularly new databases

If you have been successfully using EZproxy in proxy by port for awhile, but suddenly certain databases, particularly new databases, start exhibiting this behavior, the most common cause is a firewall configuration issue at your site.

If you are using EZproxy 3.2b (2005-04-03) or later, you can use the Test Network Connectivity option on the administration page to test for this condition.

In the most typical scenario, you install EZproxy with a default MaxVirtualHosts of 200, and your firewall administrator allows incoming access on ports 2048 and 2050-2252. You start seeing MaxVirtualHosts errors, so you increase MaxVirtualHosts to 300. The MaxVirtualHosts errors disappear, but your remote users start seeing "Page not found" and "Cannot find server or DNS" errors.

To correct this condition, your firewall (which could be on your EZproxy server, on a network device, or both) needs to be configured to allow incoming access on ports FirstPort up to FirstPort+MaxVirtualHosts+4. FirstPort defaults to 2048, so if you increase MaxVirtualHosts to 300, you would need to allow incoming access up to 2048+300+4 = 2352.

1.b. EZproxy works for all but a small number of remote users

If EZproxy works for most users, but a small number of users report these problems, it often points to a firewall restriction at the remote users site. This is most often seen when the remote user is accessing from a corporate site, and when you are using either proxy by port or proxy by hostname with a LoginPort other than 80. In this scenario, your options are to have the remote user request that the remote firewall be changed to permit access, or to move to proxy by hostname using LoginPort 80.

1.c. EZproxy gives this error to all remote users

If all remote users receive this error, you should start by verifying your DNS entry for your EZproxy server. You can check it by browsing to:

Check DNS

If you use proxy by hostname, you should select the "Check wildcard entry" option as well. This script will check all DNS servers that are registered to handle your EZproxy server name. If there are any inconsistencies in the information returned by the script, contact your network administrator to resolve this issue.

If you are using Network Address Translation (NAT), you should verify that your external address matches the DNS entry, and that the external address is properly mapped to the internal address of your EZproxy server.

2. MaxVirtualHosts Exceeded

You may have exceeded your "maximum virtual host limit." To check for this, check the file messages.txt/ezproxy.msgand look toward the end of the file for an error message like this:

Reached maximum virtual host limit, use MV in config.txt/ezproxy.cfg to increase

If you find this error, refer to MaxVirtualHosts for information on how to address it.

3. Known Problem

Check to see if the database has a recommended configuration at EZproxy Database Specific Issues

4. JavaScript

If you find that your database connections are slipping out from EZproxy, the first thing to try is the change described below that enables additional JavaScript processing. Try changing Host (H) and Domain (D) lines in your configuration to HostJavaScript (HJ) and DomainJavaScript (DJ). For example, if you are using:

Title Some Database
URL http://www.somedb.com
Domain somedb.com

change the Domain to DJ (DomainJavaScript also works, but the EZproxy documentation normally uses the shorter DJ to avoid transcription errors) such as:

Title Some Database
URL http://www.somedb.com
DJ somedb.com

When you are changing to DJ, be sure to check your config.txt/ezproxy.cfg to see if you have the database defined multiples time. If a database is defined multiple times, you should change all the instances of that database to this form.

When making this type of change, it is particularly important to follow all of the recommended steps for retesting.

5. Remote server remains proxied, but indicates that access to the database is not allowed

This behavior occurs most frequently if the IP address of your EZproxy server is not registered with the database vendor. The simplest test to verify this issue is to launch a web browser right on the EZproxy server and try accessing the real (non-EZproxy) URL of the database. If you receive the same error, then you need to contact the vendor to add the IP address of your EZproxy server to your account. When contacting support, be sure to emphasize that your browser is unable to access as this will help avoid unrelated questions about proxy server configuration.

6. "Connection refused by hostname, please try again later"

This error indicates that EZproxy is unable to connect to hostname. If this error occurs on rare occasion, it indicates that the remote server was temporarily unavailable. If this error appears constantly, it suggests that EZproxy is unable to reach the remote host. A simple test is to launch a web browser on the EZproxy server and try to access the real (non-EZproxy) URL of the database. If your web browser is blocked, then you should contact your network administrator to review outgoing firewall restrictions that may be blocking access.

7. Request support

If none of this information helps you resolve the issue, email support@oclc.org for further assistance.