ORA-12514: TNS:listener does not currently know of service

The vast majority of the time, this error results from an incorrectly specified connect descriptor in the tnsnames.ora file. Lets look at a very typical example then diagnose and fix it. After that we will dig in to how the listener comes to know of a service name.

Fig. 1 Of course the very first thing anyone should do when confronted with an Oracle error is to check the official description. There are many sources on the web, but I like to start with oerr utility on the server ..

Fig. 2

The error is pretty self-explanatory: listener does not currently know of service requested in connect descriptor. So how do we know exactly what service was requested in connect descriptor? First, do a sanity check by looking at the tnsnames.ora file.

Fig. 3 In Fig. 3, line 8 we see that we should be requesting SERVICE_NAME = fubar. At this point we know what SERVICE_NAME we should be using. We can use tnsping to confirm this

Fig. 4 Fig. 4, line 13 shows that we are requesting a connection to service fubar. Dont be fooled by the good return code. Tnsping only goes as far as confirming there is a listener at the specified ip address and port. It says nothing about any services the listener knows about. The presence of SERVCICE_NAME in the feedback is simply the result of showing the entire connect descriptor.

Now that we know what service name was actually requested, we need to check what the listener knows about. Examining the listener configuration file, listener.ora, could give some clues but it is not the whole story. In fact, the listener can be started without any listener.ora file at all. The only sure way to tell what the listener knows about is to ask it directly, with the lsnrctl command:

Fig. 5 This listener knows about three service names (vlnxora1, vlnxora1XDB, and vlnxora1_XPT), all associated with the instance vlnxora1. (The XDB and XTP services are for special use we can ignore them for general connection problems.) The vast majority of the time, thats all the debugging we need to do. We know that we should be requesting a connection to service vlnxora1 instead of fubar. Since that request comes from the client, we have to fix tnsnames.ora

Fig. 6 We see in Fig. 6, line 12 that we have made the necessary correction in tnsnames.ora. The subsequent connection request is successful (fig. 6, line 18), thus validating our analysis and corrective action.

Registering the service with the listener

So how did the listener come to know about service vlnxora1 in the first place? There are two methods by which a service is registered with the listener static and dynamic. Well discuss each in turn.

Static registration
Static registration is accomplished by configuring the SID_LIST section of the listener.ora file.

Fig. 7 In Fig. 7 we see three SIDs listed: PLSExtProc, fubar, and vlnxora1 (lines 7,14, and 19). Checking the status of the listener, we get

Fig. 8 Notice the entry for service myfubardb (fig. 8, line 25) maps back to (GLOBAL_DBNAME=myfubardb) (fig 7, line 12) and is related to instance fubar, which maps to fig 7, line 14). Further, notice that its status is UNKNOWN. This status of UNKNOWN is the indication that this registration came from the SID_LIST section of listener.ora. It is unknown because the listener doesnt make a check to see if there is an instance named fubar broadcasting a service name of myfubardb. The listener is just saying if you ask for a connection to myfubardb, Ill see what I can do to service it. In fact, I have no database named fubar or myfubardb. Notice also that service vlnxora1 has two instances, one unknown, and one READY. Like myfubardb, the UNKNOWN vlnxora1 comes from listener.ora (fig. 7, line 19); the READY instance comes from the database having registered with the listener (dynamic registration).

Again, for our current discussion, we can ignore the services vlnxora1XDB and vlnxora1_XTP. These have special internal uses for Oracle. For the remainder of the discussion, I am going to completely remove listener.ora, then restart the listener so that it has no static registrations and is running with all default values:

Fig. 9 With no static registration the listener will start with all default values and support no services until a pmon process registers itself.

Dynamic registration

Dynamic registration is accomplished when the pmon process of the database instance contacts the listener and requests registration. This occurs at instance startup, and every few minutes during the life of the instance. There are three initialization parms that affect what service name(s) pmon will register with the listener: DB_NAME SERVICE_NAMES DB_DOMAIN You should look up each one in the Reference Manual and read the descriptions. (Click on the links) Notice particularly in the description of SERVICE_NAMES the following: If you do not qualify the names in this parameter with a domain, Oracle qualifies them with the value of the DB_DOMAIN parameter. If DB_DOMAIN is not specified, then no domain will be applied to the non-qualified SERVICE_NAMES values. There is another interaction that is not spelled out in the Reference Manual, but mentioned in the Net Services Administrators Guide: The service name defaults to the global database name, a name comprising the database name (DB_NAME parameter) and domain name (DB_DOMAIN parameter) Since neither DB_DOMAIN nor SERVICE_NAMES are required parameters, lets start with an instance with neither of those set, then start observing how service names get constructed with various settings. For each iteration I will do the following: 1) alter an initialization parm 2) bounce the database (some of the parms require it. To keep things clean and consistent, Ill do it for all of them) 3) restart the listener, to flush the old registrations 4) force a new registration 5) show the listener status, with the results of the new registration 6) show the values of all three parms, for comparison

Fig. 10 In Fig. 10, at lines 91,93 and 95, we see three service names. All three are associated with the instance vlnxora1 and derived their name from the initialization parameter db_name. Next, we add a simple service name. While normal practice might be to make it the same as the db_name, Ill make it different so that we can trace it to the end result. Remember, it is quite acceptable to have multiple service_names, which we will get to in a moment.

Fig. 11 Now we see that all of the service names derived from db_name are still in place, but we have also added one derived from service_names (Fig. 11, line 27)

Next we set db_domain

Fig. 12

Notice that all service names those derived from db_name as well as the one derived from service_names have the value of db_domain appended to them. Next we add a second service name, this one qualified with a second domain name. Not something youd normally do, but useful for demonstrating the interaction of the parameters

Fig. 13 As before, all of the unqualified service names derived from db_name and service_names have been qualified with the value of db_domain. But notice that we have a new service name (Fig. 13, line 35) from the second value supplied from service_names. Since this was fully qualified in the service_names initialization parm, the value of db_domain was not applied.

Conclusion
We have explored the relationship between the connect descriptor issued by the client and the services supported by the listener, as well as the factors that control what services the listener supports. In the concluding post in this series, I will discuss how the database locates the listener in order to register its services the LOCAL_LISTENER initialization parameter.