Oracle · error reference
ORA-12154: TNS could not resolve the connect identifier
ORA-12154: TNS:could not resolve the connect identifier specified
The client was given a name it could not turn into an address. It never reached the database — the problem is entirely on the client's side.
What the database is telling you
A connect identifier like ORCL or PRODDB is an alias that Oracle clients resolve through tnsnames.ora (or a directory service) into host, port and service. ORA-12154 means no resolver the client consulted knows that alias — the file was not found, is in a different directory, or does not contain that name.
Why it shows up in a migration
Connection details copied from a DBA's SQL Developer setup are often an alias that only resolves on their machine. A migration tool running elsewhere has a different tnsnames.ora — or none.
Common causes
- The alias is not in the tnsnames.ora the client reads, or is misspelled (including domain suffixes like ORCL.WORLD).
- TNS_ADMIN points somewhere else, or the client never looks where the file is.
- An EZConnect string is malformed, so the client treats it as an alias.
- The tnsnames.ora entry has a syntax error (an unbalanced bracket hides every entry after it).
How to fix it
- 1
Skip the alias: connect with EZConnect, host:port/service_name. No tnsnames.ora involved.
db.example.com:1521/ORCLPDB1
- 2
If the alias must stay, point the client at the directory holding tnsnames.ora.
export TNS_ADMIN=/opt/oracle/network/admin
- 3
Get the real service names from the database (or ask the DBA), so the EZConnect string is right first time.
SELECT name FROM v$services;
- 4
If the next error is ORA-12514, the host and port are right but the service name is not one the listener knows.
What DBShifts does about it
DBShifts connects to Oracle by host, port and service (EZConnect, in the driver's thin mode), so no tnsnames.ora is needed. Connection diagnosis reports ORA-12154 as the database not being found, with the hint to make the service name match exactly what the server exposes.
Connection diagnosis
Connecting a database?
Add the database to DBShifts and the connection is tested on the spot. If it fails, you get which of these errors it is and what to change — not the driver's raw message. Once it connects, browse it, migrate it, or let an AI agent read it through the gateway with sensitive columns masked.