The application can’t connect. The error is one every Oracle DBA has seen:

ORA-12514: TNS:listener does not currently know of service requested in connect descriptor

Newer clients word it more plainly. The 26ai client in this post’s lab says:

ORA-12514: Cannot connect to database. Service FREEPDB is not registered with the listener
at host 127.0.0.1 port 1521.

The database is up. You can log in on the server. So someone restarts the listener, and now nothing can connect for a minute.

ORA-12514 is a precise message, and it’s good news of a kind: the listener answered. It’s running, the host and port are right, and the network path works. What it doesn’t have is a service by the name the client asked for. The database behind it may be perfectly healthy. This post covers how services get to the listener, the four common reasons one is missing, and how to tell ORA-12514 from its neighbours. It ends with a lab where restarting the listener causes a minute of ORA-12514 for every service, and one ALTER SYSTEM REGISTER closes the gap at once.

How a service gets to the listener

The listener doesn’t know what databases exist. The database tells it. A background process (LREG) in each instance registers the instance’s services with the listener: FREEPDB1, each application service, the CDB’s own service. It does that at startup, whenever a service starts or stops, and periodically after that. The listener keeps that list in memory only.

A client connects by asking for a service: host:1521/FREEPDB1 in EZConnect, or SERVICE_NAME=FREEPDB1 in a tnsnames.ora descriptor. If the listener has a registered service by that name, it hands the connection to the instance. If not, it refuses with ORA-12514.

So ORA-12514 has exactly two kinds of cause: the client asked for the wrong name, or the right name isn’t registered with this listener right now. lsnrctl services (or lsnrctl status) shows what the listener has:

Services Summary...
Service "FREE" has 1 instance(s).
Service "FREEXDB" has 1 instance(s).
Service "freepdb1" has 1 instance(s).
Service "orders_app" has 1 instance(s).

If the service is in that list, look at the client. If it isn’t, look at the database.

Which error do you actually have?

Five errors get mixed up in tickets. They fail at different points in the connection, so they point to different fixes:

ORA-12154   the alias wasn't found (tnsnames.ora, LDAP)    the client never reached a listener
ORA-12541   no listener at that host and port              wrong host/port, listener down, firewall
ORA-12505   the listener doesn't know that SID             often a PDB name given as a SID
ORA-12514   the listener doesn't know that SERVICE         this post
ORA-12504   no service name given, and no default service  incomplete connect string

ORA-12505 is the usual developer version. jdbc:oracle:thin:@db01:1521:FREEPDB1 (a colon before the name) asks for a SID, which is an instance, not a PDB. jdbc:oracle:thin:@//db01:1521/FREEPDB1 (a slash) asks for the service, which is what a PDB is reached by.

⤢ Enlarge

Prove it

The lab runs Oracle Database Free in a container. It creates an application service, orders_app, in the pluggable database FREEPDB1 the way many shops do: with DBMS_SERVICE, started by hand. Then it breaks the connection four ways, with the database up and healthy every time:

case                                     result                                   fix
FREEPDB instead of FREEPDB1              ORA-12514; FREEPDB1 connects fine        fix the connect string
listener restarted                       ORA-12514 for every service, ~60 s       ALTER SYSTEM REGISTER
PDB closed and opened                    PDB READ WRITE, orders_app ORA-12514     start it + SAVE STATE
second listener on port 1522             "supports no services", ORA-12514        LOCAL_LISTENER

Don’t take my word for it — run it. The listener-service lab asserts every row: ORA-12514 for the wrong name and the right name still connecting; ORA-12514 right after a listener restart and recovery once the database re-registers; the app service missing after a PDB restart and surviving the next one after SAVE STATE; and the second listener refusing until LOCAL_LISTENER names it. It also asserts ORA-12154, ORA-12541 and ORA-12505 for their cases. If any of that doesn’t reproduce, the run fails. Proven on every CI push.

Cause 1: the wrong name

The most common cause, and the easiest to miss because the name looks right. FREEPDB instead of FREEPDB1, orders instead of orders_app, a domain mismatch (the database has a DB_DOMAIN, so its service is freepdb1.example.com, and the client asks for plain freepdb1, or the other way round), or a connect string still pointing at the old database’s service name after a migration.

You don’t have to guess which app is asking for what. The listener log records every refused connect with the service the client requested, the client program, and the client host. From the lab:

(CONNECT_DATA=(SERVICE_NAME=FREEPDB)(CID=(PROGRAM=sqlplus)(HOST=...)(USER=oracle)))
  * (ADDRESS=(PROTOCOL=tcp)(HOST=127.0.0.1)(PORT=59690)) * establish * FREEPDB * 12514
TNS-12514: listener does not currently know of service requested in connect descriptor

Even on 26ai the log uses the classic text. lsnrctl status prints the log’s location. On a busy listener, grep it for 12514 and count by SERVICE_NAME and HOST: the typo and the server it lives on fall out in one command.

Cause 2: the listener was restarted

This is the one that turns a small problem into an outage. A listener knows only what’s been registered with it since it started. Restart it, and for a while it knows nothing:

$ lsnrctl status
...
The listener supports no services

Every service gets ORA-12514 until the database registers again on its own. In the lab that took about a minute, every time: 61 seconds of refused connections for every service, caused entirely by the restart. Restarting the listener to “fix” ORA-12514 makes it worse.

The database can be told to register right now:

ALTER SYSTEM REGISTER;

In the lab, after the same restart, the connection works immediately after this command. Run it in every instance (and every RAC node) whose services that listener serves. lsnrctl reload re-reads listener.ora without a stop/start, but don’t count on it keeping the registrations: in the lab it sometimes kept every one and sometimes dropped them all. Follow a reload with ALTER SYSTEM REGISTER too.

Cause 3: the service didn’t come back with the database

The PDB is open. FREEPDB1 connects. The application’s service doesn’t:

FREEPDB1 is READ WRITE; active services: freepdb1
localhost:1521/FREEPDB1    -> connected
localhost:1521/orders_app  -> ORA-12514: ... Service orders_app is not registered with the listener ...

A service created with DBMS_SERVICE and started by hand is running only until the next time the PDB closes. After a patch, a server reboot or a switchover, the PDB comes back and its default service with it, but nothing starts orders_app. The database is fine. The application is down.

On a single instance, start the service and save the PDB’s state, so it reopens with the same services running:

ALTER SESSION SET CONTAINER = FREEPDB1;
EXEC DBMS_SERVICE.START_SERVICE('orders_app')
ALTER PLUGGABLE DATABASE FREEPDB1 SAVE STATE;

The lab restarts the PDB again after this, and orders_app connects. Under Grid Infrastructure or RAC, define the service in Clusterware instead (srvctl add service -db ... -pdb FREEPDB1 -service orders_app) and it starts with the database. With Data Guard, the same command takes -role PRIMARY, so the application’s service runs only where the primary is, and follows it on switchover. That last case is outside what the lab builds.

Cause 4: a listener the database doesn’t register with

A new listener on port 1522, for an application tier or a firewall rule, or a listener moved off 1521. Clients pointed at it get ORA-12514, and its status says why:

$ lsnrctl status LISTENER2
...
The listener supports no services

The database registers only with the listeners it knows about. By default that’s the local listener on port 1521. Any other address has to be in LOCAL_LISTENER (or REMOTE_LISTENER, for RAC and SCAN):

ALTER SYSTEM SET local_listener =
  '(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=db01)(PORT=1521))(ADDRESS=(PROTOCOL=TCP)(HOST=db01)(PORT=1522)))'
  SCOPE = BOTH;

In the lab, both services connect through port 1522 right after this; changing the parameter triggers a registration. (The lab uses SCOPE = MEMORY so a rerun starts clean.) On a Grid Infrastructure node, the agent manages LOCAL_LISTENER; register a new listener with srvctl instead of setting it by hand.

The checklist

When ORA-12514 comes in, in this order:

1. Read the full message. The service name and the host and port the client used are in it (newer clients) or in the listener log (all releases).
2. lsnrctl services on that host. Is the service listed? If yes, the client has the wrong name or the wrong listener.
3. SELECT name FROM v$active_services in the database (in the PDB). Is the service running? If not, start it, and make sure it starts next time (SAVE STATE or srvctl).
4. SHOW PARAMETER local_listener. Does it include the address the client is using?
5. ALTER SYSTEM REGISTER. Re-registers everything now. Harmless, instant, and much better than a listener restart.

What teams get wrong

• Restarting the listener first. It refuses every service until the database re-registers, about a minute in the lab. If a restart or a reload really is needed, follow it with ALTER SYSTEM REGISTER.
• Treating ORA-12514 as “the database is down.” It’s a naming or registration problem. The lab’s database was up and open through every case.
• Starting app services by hand. They don’t survive a PDB restart. Use SAVE STATE or Clusterware, and test it by restarting the PDB before the patch weekend does it for you.
• Giving a PDB name as a SID. That’s ORA-12505, not ORA-12514. PDBs are reached by service name: /FREEPDB1, not :FREEPDB1.
• Relying on a default service. The lab’s container has DEFAULT_SERVICE_LISTENER set, so a connect string with no service name quietly lands in the CDB root. Without that parameter it fails with ORA-12504. Neither is where the application should be; always name the service.

Frequently asked questions

What does ORA-12514 TNS:listener does not currently know of service requested in connect descriptor mean?

It means the client reached a listener, and the listener has no registered service with the name the client asked for. The listener is up and reachable; the database may be healthy too. Either the client asked for the wrong service name (a typo, a missing or extra domain, an old name after a migration), or the right service isn't registered with that listener: because the listener was just restarted, the service isn't running, or the database doesn't register with that listener. Newer clients word the same error as 'Cannot connect to database. Service X is not registered with the listener at host ... port ...'.

How do I fix ORA-12514?

Run lsnrctl services on the database host and check whether the service is listed. If it is, fix the client's connect string; the listener log records the exact service name each refused client asked for. If it isn't, check v$active_services in the database: start the service if it's stopped and make it start automatically (SAVE STATE on a single instance, srvctl under Grid Infrastructure). Check that LOCAL_LISTENER includes the listener's address. Then run ALTER SYSTEM REGISTER to register everything with the listener immediately.

Why do I get ORA-12514 after restarting the listener?

Because a newly started listener knows no services. The database registers its services again on its own, which took about a minute in the companion lab, and until then every service is refused with ORA-12514. ALTER SYSTEM REGISTER in each instance makes the database register immediately. lsnrctl reload, which re-reads listener.ora without a stop/start, sometimes dropped the registrations in the lab too, so follow it with ALTER SYSTEM REGISTER as well.

What is the difference between ORA-12514, ORA-12505, ORA-12541 and ORA-12154?

They fail at different steps. ORA-12154 means the client couldn't resolve the alias (in tnsnames.ora or LDAP) and never reached a listener. ORA-12541 means nothing is listening at that host and port. ORA-12505 means the listener doesn't know the SID requested, often because a PDB name was given as a SID (host:1521:PDB instead of //host:1521/PDB). ORA-12514 means the listener answered but has no service by the requested name.

Why does my PDB's application service disappear after a restart?

A service created with DBMS_SERVICE and started manually is not started automatically when the PDB opens again. The PDB and its default service come back, so the database looks healthy, but connections to the application service fail with ORA-12514. On a single instance, start the service and run ALTER PLUGGABLE DATABASE ... SAVE STATE so the PDB reopens with the same services. Under Grid Infrastructure or RAC, create the service with srvctl add service so Clusterware starts it, with -role PRIMARY for Data Guard.

Does ORA-12514 mean the database is down?

No. ORA-12514 is about registration and naming, not database health. In the companion lab the database was up and the PDB open READ WRITE in every case that produced ORA-12514. If the instance were down, a listener with only dynamic registration would also report ORA-12514, so check both: lsnrctl services for what the listener has, and the instance itself for whether it's running.

ORA-12514 is a listener telling you exactly what’s wrong: it’s here, and it doesn’t have that name. Before you restart anything, compare what the client asked for (the listener log) with what the listener has (lsnrctl services), and let that point you at the client or the database. Then register, don’t restart. It sits with the other Oracle Net settings worth getting right, like network encryption, and with the cutover-weekend surprises like the sequence that wasn’t moved. Then prove it the way that ends the argument — with the listener-service lab, where a listener restart refuses every service for a minute and one ALTER SYSTEM REGISTER brings them all back.