ORA-12514 and ORA-12154: SID vs Service Name vs TNS, Explained

Posted by Kyle Hankinson August 11, 2026

---

Someone hands you a host, a port, and "the database name", you type them into a client, and Oracle answers with this:

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

That is the current wording; releases before 23ai phrase it as ORA-12514: TNS:listener does not currently know of service requested in connect descriptor, which is the string most search results still show. Either way, the error never says what is usually wrong: you gave the right name of the wrong kind, or the right kind with a stale name. Oracle has three different ways to identify a database, and every ORA-125xx error is really telling you which layer of the connection gave up.

The three identifiers

SID (system identifier) names an instance, the set of Oracle processes and memory running on the server. It is the oldest scheme, and old JDBC strings use it with a colon: host:1521:ORCL.

Service name is what an instance registers with the listener. One instance can register several services, and since Oracle 12c each pluggable database (PDB) registers its own. EZConnect uses a slash: host:1521/FREEPDB1.

TNS alias is a client-side nickname (like PRODDB) that your local tnsnames.ora file expands into a full host/port/service descriptor. The server is not involved in resolving it at all. Oracle's Net Services guide covers how registration and resolution fit together.

The colon-versus-slash distinction matters more than it looks. host:1521:FREEPDB1 asks the listener for a SID named FREEPDB1; host:1521/FREEPDB1 asks for a service. Same characters, different question, different error when it fails.

One error per layer

A connection attempt passes through your client config, the network, the listener, and finally database authentication. Each stage has its own failure code, so the error you get locates the problem for you:

Error	Layer that failed	What it actually means
ORA-12154	your machine	The TNS alias could not be resolved. The server was never contacted.
ORA-12541	network	Nothing is listening at that host and port. Wrong port, server down, or a firewall.
ORA-12514	listener	The listener is up but no service by that name is registered.
ORA-12505	listener	The listener is up but no SID by that name is registered.
ORA-01017	database	You reached the database. Username or password is wrong.

I reproduced all five against Oracle Database Free 23ai running in Docker (gvenzl/oracle-free:23-slim), and the modern messages are refreshingly explicit. A wrong SID:

ORA-12505: Cannot connect to database. SID FREEPDB1 is not registered
with the listener at host 127.0.0.1 port 1521.

Note what happened there: FREEPDB1 is a perfectly valid service on that server, but I asked for it as a SID and the listener refused. That single test is the whole SID-versus-service confusion in miniature. A wrong port:

ORA-12541: Cannot connect. No listener at host 127.0.0.1 port 1599.

An alias missing from tnsnames.ora:

ORA-12154: Cannot connect to database. Cannot find alias PRODDB in
/opt/oracle/product/26ai/dbhomeFree/network/admin/tnsnames.ora.

ORA-12154 deserves special emphasis because people burn hours restarting servers over it: the message names a file on your own machine. The network was never touched. Fix the alias, point TNS_ADMIN at the right directory, or skip TNS entirely and use host:port/service directly.

And with everything right except the password:

ORA-01017: invalid credential or not authorized; logon denied

One footnote on ORA-01017: passwords have been case-sensitive since 11g, so a password that worked on an ancient system in uppercase may fail verbatim on a newer one.

Finding the service name you actually need

When ORA-12514 strikes, stop guessing and ask the server what it has. On the database host:

$ lsnrctl status
...
Services Summary...
Service "FREE" has 1 instance(s).
Service "FREEXDB" has 1 instance(s).
Service "freepdb1" has 1 instance(s).

Or, from any session that can connect (a DBA, or you via a different tool):

SELECT name FROM v$services;

On my container that returns exactly one row, freepdb1, which is the service application connections should use. Service names are case-insensitive when you connect, so FREEPDB1 works fine.

Why your old SID stopped working: multitenant

Since 12c, Oracle's multitenant architecture splits a server into a container database (CDB) and pluggable databases (PDBs), and from 21c on, multitenant is the only option. Your tables live in a PDB, and a PDB is reachable only by service name. It has no SID.

This is the story behind most "it worked before the upgrade" tickets. The old host:1521:ORCL string named the instance; after migration to multitenant, that instance is the CDB, and your schema now lives in a PDB like ORCLPDB1. Depending on the driver, the SID string either fails outright or, worse, connects you to the CDB root where none of your tables exist, producing mysterious ORA-00942 errors on tables you can see in another tool. On the Docker image the split is visible immediately: service FREE is the CDB, FREEPDB1 is the PDB where the app user's schema lives.

The rule of thumb for anything modern: use the service name, with a slash. Reserve SID syntax for legacy servers that genuinely predate services, which in practice means almost nothing still in production.

Plugging the right value into a GUI client

Connection editors mirror the same distinction, so this decoder maps directly onto the form fields. SQLPro Studio's Oracle connection editor, for example, takes a host, a port, and a name you mark as either a service name or a SID; choosing the wrong kind produces exactly the ORA-12514 or ORA-12505 you would get on the command line, so the table above tells you which toggle to flip. For a local playground, docker run -d -p 1521:1521 -e ORACLE_PASSWORD=test gvenzl/oracle-free:23-slim gives you a server whose answers are always the same: port 1521, service name FREEPDB1.

A last diagnostic habit worth keeping: read the error as a progress report. ORA-12154 means you never left the laptop. ORA-12541 means you found the machine but not the listener. ORA-12514 and ORA-12505 mean the listener heard you and vetoed the name. ORA-01017 means the whole network path is fine and only the credentials are wrong, so stop editing tnsnames.ora. Each code eliminates every layer before it, and working through them in order beats changing three settings at once.

Once you are connected, Oracle has a few more surprises waiting for arrivals from other databases; the first one most people hit is pagination, covered in Oracle pagination: ROWNUM vs FETCH FIRST. Oracle also maintains reference pages for each code at docs.oracle.com/error-help, and current releases print that link under the error message itself.

---