Common Error Messages
Ideally, your installation, configuration, and use of SQL*Net will go smoothly, and you will have no problems. However, inevitably errors will occur. All the error messages you may receive when using Oracle networking products are described in the Oracle Network Products Troubleshooting Guide. However, for your convenience, this appendix describes seven of the most common error messages in detail. They are:
- ORA-12154 ``TNS:could not resolve service name"
- ORA-12198 ``TNS:could not find path to destination"
- ORA-12203 ``TNS:unable to connect to destination"
- ORA-12500 ``TNS:listener failed to start a dedicated server process"
- ORA-12533 ``TNS:illegal ADDRESS parameters"
- ORA-12545 ``TNS:name lookup failure"
- ORA-12560 ``TNS:protocol adapter error"
For information on other error messages, and to learn more about error logging and the trace facility, see the Oracle Network Products Troubleshooting Guide.
Common Sources of Error: Configuration Files
The most common cause of problems in making a SQL*Net connection is in the structure or location of the configuration files.
Syntax Errors
The syntax of the files must be followed precisely. If you create the files using Network Manager, syntax errors should not occur. However, if you create or edit them by hand, check them carefully to see that all the appropriate parentheses are in place, that the lines are indented to show their logical structure, and that there are no typographical errors. See Appendix B, "Syntax Rules for Configuration Files," for details on the syntax of these files. Be sure that all service names are mapped to connect descriptors in the TNSNAMES. ORA file.
Location Errors
The TNSNAMES.ORA file must be distributed so that it is available to all nodes that make connections using SQL*Net version 2 (unless Oracle Names is being used on the network).
A unique LISTENER.ORA file must be distributed to each node that includes one or more databases.
In a network that includes one or more Interchanges, a unique TNSNAV.ORA file must be available to all the clients which have similar navigation requirements.
Every node with an Interchange must have an INTCHG.ORA, a TNSNET.ORA, and a TNSNAV.ORA file.
See the Oracle operating system specific manual for your platform for the exact locations of these files.
Common Sources of Error: Inactive Components
Before you can use a SQL*Net network, a transport layer protocol and an Oracle Protocol Adapter must be installed.
Be sure that you have started the listener for any server you intend to contact. For instructions on starting the listener using the Listener Control Utility, see Chapter 5, ``Using SQL*Net".
If you are making a connection across protocols using one or more Interchanges, the Interchanges must be started. For instructions on starting an Interchange using the Interchange Control Utility, see Chapter 6 in the Oracle MultiProtocol Interchange Administrator's Guide.
Common Error Messages
The following error messages are among those most often encountered by SQL*Net users. For a complete list of SQL*Net error messages, their causes and the action to take if you get them, see Chapter 3 in the Oracle Network Products Troubleshooting Guide.
ORA-12154 TNS:could not resolve service name
This error points to a problem related to Oracle Names or the TNSNAMES.ORA file. The service name specified cannot be located through either a Names Server or the TNSNAMES.ORA file. If you get this error, do the following:
- If you are using Oracle Names:
- Use the Names Control Utility STATUS or PING commands to see if a Names Server is available. For example, enter the following:
namesctl status names_server_name
- Use the Names Control QUERY command to find out if the service name and address are stored on a Names Server.
For example, enter the following:
namesctl query service_name *
- If you are using a TNSNAMES.ORA file:
- Verify that a TNSNAMES.ORA file exists and is in the proper place and accessible. See the Oracle operating system-specific manual for your platform for details on the required name and location.
- Check to see that the service name is mapped to a connect descriptor in the TNSNAMES.ORA file and add or correct it if necessary.
- Make sure there are no syntax errors anywhere in the file. Particularly look for unmatched parentheses or stray characters. Any error in a TNSNAMES.ORA file makes it unusable. See Appendix B, "Syntax Rules for Configuration Files," for details on the syntax of this file.
ORA-12198 TNS:could not find path to destination
This error indicates a failure of navigation across protocols through one or more Interchanges. If you get this error, do the following:
- Verify that the Interchanges are active. (Use the STATUS command of the Interchange Control Utility.) If necessary, turn on the Interchanges with the START command of the Interchange Control Utility (INTCTL). For information about how to use the Interchange Control Utility, see Chapter 6 of the Oracle MultiProtocol Interchange Administrator's Guide.
- Verify that each Interchange has enough pump capacity to make another connection. (Use the STATUS command of INTCTL.) If not, wait and try to make the connection later.
- If the Interchanges seem to be functioning correctly, check the TNSNAMES.ORA file to verify that the correct community is included in the ADDRESS section of the connect descriptor of the service name you are using. Also check the client's TNSNAV.ORA file to be sure that the correct address is included for the preferred Connection Managers.
If the error persists, it may be useful to check for errors in the Interchange log files. A different error in the connection process can sometimes be reported as a 12198.
ORA-12203 TNS:unable to connect to destination
This message indicates that the client is not able to find the desired database. If you get this message, do the following:
- Be sure you have entered the service name you wish to reach correctly.
- Look at the TNSNAMES.ORA file to see that the ADDRESS parameters in the connect descriptor for the service name are correct.
- Use the Listener Control Utility to verify that the listener on the remote node is up and listening. If it is not, use the Listener Control Utility to start it. For instructions on starting the listener using the Listener Control Utility, see Chapter 5, ``Using SQL*Net."
This error often is reported because the destination node is not available or because of unrelated network problems.
ORA-12500 TNS:listener failed to start a dedicated server process
This message indicates that the listener was unable to start a process connecting the user to the database server. The most likely cause is that the SID_LIST section of the LISTENER.ORA file or the system identifier (SID) in the CONNECT DATA section of the TNSNAMES.ORA file is incorrect. Check each of these files.
Another possible cause of this message is that the user does not have adequate privileges to access the database. Ask your database administrator to provide you access privileges if you do not have them. Also ask your system administrator to check the ownership and permissions of the database server process image.
ORA-12533 TNS:illegal ADDRESS parameters
This message occurs if the protocol specific parameters in the ADDRESS section of the designated connect descriptor in TNSNAMES.ORA are incorrect. The protocol specific keywords, and their acceptable values, can be found in the Oracle operating specific documentation for your platform.
If you use Network Manager to create the TNSNAMES.ORA file, the correct protocol specific keywords are included automatically.
ORA-12545 TNS:name lookup failure
This message occurs when the listener on the remote node cannot be contacted. The ADDRESS in the TNSNAMES.ORA file or the LISTENER.ORA file may be incorrect. This message may also appear if the listener on the remote node has not been started. Check its status with the STATUS command of the Listener Control Utility, and start it with the START command if necessary.
ORA-12560 TNS:protocol adapter error
This message indicates that there is a problem at the protocol adapter level. That is, SQL*Net and the Interchange are functioning correctly, but there is something wrong with the protocol adapter that underlies them. The Oracle operating system-specific documentation for your platform contains more information about the protocol adapters.
In order to get more information about the specific problem, turn on tracing and re-execute the operation. (Because tracing and trace files use a lot of disk space, be sure to turn off tracing as soon as the trace is complete.) The trace file includes information about the specific protocol adapter problem. If you have trouble interpreting the trace file, contact Worldwide Customer Support for assistance, following the procedures described in Chapter 1 of the Oracle Network Products Troubleshooting Guide.