- Error code
- ORA-12154
- Product
- Oracle Database
- Versions
- Oracle Database 19c, 21c, 23ai and 26ai clients (wording differs: see below)
- Category
- Connectivity & Listener
- Last reviewed
- 24 October 2026
On this page
What it means
ORA-12154 means the Oracle client could not turn the name after the @ (the alias or connect identifier) into a connect descriptor with any of its configured naming methods, so it never tried to reach a database.
When you connect as shop@SALESDB, the client first has to translate SALESDB into a full address (host, port and service name). It tries the naming methods listed in NAMES.DIRECTORY_PATH in sqlnet.ora, which defaults to (tnsnames, ezconnect, ldap): a tnsnames.ora file, an Easy Connect string such as host:port/service, or an LDAP directory. If none of them produces a descriptor, the connection fails with ORA-12154 before any network traffic is sent, so the database, the listener and the password are not the problem yet.
Current releases say which alias could not be found and where the client looked (for example the tnsnames.ora file it read), which usually shows the problem at once: a misspelt alias, or a different file from the one you edited. Oracle Database 19c and 21c print only the generic "TNS:could not resolve the connect identifier specified". For a database link, the name is resolved on the database server, not on your machine.
Common causes
- The alias is misspelt, or does not exist in the tnsnames.ora file the client reads.
- The client reads a different tnsnames.ora from the one you edited: the TNS_ADMIN environment variable points elsewhere, there are several Oracle homes, or Instant Client uses its own network/admin directory.
- A syntax error in tnsnames.ora, such as an unmatched parenthesis or stray character, makes the file (or the entry) unusable.
- The entry is defined with a domain (DEV1.WORLD) but the client looks up a plain name (DEV1) and NAMES.DEFAULT_DOMAIN is not set, or the other way round.
- NAMES.DIRECTORY_PATH in sqlnet.ora does not list the naming method you rely on (tnsnames, ezconnect or ldap).
- An Easy Connect string names a host that the client cannot resolve, or the LDAP directory used for naming is not reachable.
- A database link uses a name that is missing from the tnsnames.ora on the database server.
Diagnose it
Read-only These queries only read the data dictionary (USER_, ALL_ and DBA_ views) and dynamic performance views (V$). They do not change data, privileges or settings, so they are safe to run first. DBA_ and V$ views need the matching privileges.
Ask the client how it resolves the name (tnsping)
tnsping resolves the alias the same way the client does and prints the parameter files it used. Oracle notes that it only shows a listener can be reached, not that the database works, but for ORA-12154 the resolution step is exactly what you need to see.
tnsping SALESDB"Used parameter files:" shows which sqlnet.ora was read. A good alias shows "Used TNSNAMES adapter to resolve the alias" and the full descriptor. "TNS-03505: Failed to resolve name" confirms the name cannot be resolved from this machine.
Which configuration directory is the client using?
The client looks in the directory named by TNS_ADMIN first, then in ORACLE_HOME/network/admin (Instant Client uses its own network/admin subdirectory). Check what is set in the same shell or service account that runs the failing program.
# Linux and macOS
echo $TNS_ADMIN
ls -l $ORACLE_HOME/network/admin
# Windows (cmd)
echo %TNS_ADMIN%
dir "%ORACLE_HOME%\network\admin"The directory that holds the tnsnames.ora and sqlnet.ora actually in use. If TNS_ADMIN is empty or points elsewhere, the file you edited may never be read.
Check the naming settings in sqlnet.ora
grep -i -E 'NAMES.DIRECTORY_PATH|NAMES.DEFAULT_DOMAIN' $TNS_ADMIN/sqlnet.oraNAMES.DIRECTORY_PATH must include tnsnames for aliases and ezconnect for host:port/service strings. If NAMES.DEFAULT_DOMAIN is set, its value is appended to a plain alias, so SALESDB is looked up as SALESDB.example.com.
Bypass naming with an Easy Connect string
If connecting with the host, port and service name directly works, the database is fine and only the alias lookup is broken.
sqlplus shop@//sales-server.example.com:1521/salespdb.example.comA password prompt and a session mean the problem is the tnsnames.ora entry or the client configuration. A different error, such as ORA-12541 or ORA-12514, moves you to the next step of the connection.
For a database link: which name does it use?
The HOST column holds the connect string the link uses; it is resolved by the database server with its own Oracle Net files.
SELECT db_link, username, host
FROM user_db_links;The alias or descriptor stored in the link. That alias must exist in the tnsnames.ora used by the database server process.
How to fix it
Each fix is labelled with what it changes. Try read-only checks and the least invasive fix first, and test changes outside production.
Add or correct the entry in the tnsnames.ora the client reads
Client or network sideEdit the file in the directory you found above. Keep the parentheses balanced; one broken entry can make the rest of the file unusable.
SALESDB =
(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = sales-server.example.com)(PORT = 1521))
(CONNECT_DATA =
(SERVICE_NAME = salespdb.example.com)
)
)Point the client at the right configuration directory
Client or network sideSet TNS_ADMIN for the user or service that runs the program, so every tool reads the same files. Restart the program afterwards so it picks up the variable.
# Linux and macOS
export TNS_ADMIN=/opt/oracle/network/admin
# Windows (cmd), for the current session
set TNS_ADMIN=C:\oracle\network\adminUse Easy Connect and skip tnsnames.ora
Client or network sideFor a single database an Easy Connect string needs no file at all: host[:port]/service_name. The port defaults to 1521. Make sure ezconnect is in NAMES.DIRECTORY_PATH if that parameter is set.
sqlplus shop@//sales-server.example.com:1521/salespdb.example.com
-- JDBC thin URL with the same values
-- jdbc:oracle:thin:@//sales-server.example.com:1521/salespdb.example.comMatch the domain of the alias
Client or network sideOracle's own troubleshooting example: the alias is DEV1.WORLD in tnsnames.ora but the client connects to DEV1. Either connect with the full name or add the default domain to sqlnet.ora so it is appended to plain names.
# sqlnet.ora
NAMES.DIRECTORY_PATH = (TNSNAMES, EZCONNECT)
NAMES.DEFAULT_DOMAIN = WORLDFix the name on the database server for database links
Changes configurationWhen ORA-12154 comes from a query over a database link, add the alias to the tnsnames.ora used by the database server (in its TNS_ADMIN or ORACLE_HOME/network/admin), not to your own machine. Test it on the server with tnsping before using the link again.
Examples
A misspelt alias
Not reproduced here: no Oracle Database is installed for this site. The result shows the message format documented in Oracle's error reference for current releases; the alias is this example's and the file path is illustrative (it is wherever your client's tnsnames.ora lives). Oracle Database 19c and 21c clients print "ORA-12154: TNS:could not resolve the connect identifier specified" instead.
# tnsnames.ora defines SALESDB
sqlplus shop@SALEDBORA-12154: Cannot connect to database. Cannot find alias SALEDB in /opt/oracle/network/admin/tnsnames.ora.
An alias with a domain that the client does not append
Not reproduced here: no Oracle Database is installed for this site. The files follow the TNS-12154 troubleshooting example in Oracle's Net Services Administrator's Guide (19c), and the result is the 19c wording from Oracle's error reference. Adding NAMES.DEFAULT_DOMAIN = WORLD to sqlnet.ora, or connecting to DEV1.WORLD, resolves it.
# tnsnames.ora
DEV1.WORLD =
(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = 192.0.2.56)(PORT = 1521))
(CONNECT_DATA = (SERVICE_NAME = sales.example.com))
)
# sqlnet.ora has no NAMES.DEFAULT_DOMAIN
sqlplus shop@DEV1ORA-12154: TNS:could not resolve the connect identifier specified
How to prevent it
Keep one set of Oracle Net files per machine and point every tool and service at it with TNS_ADMIN, so there is no second tnsnames.ora that only some programs read. Prefer Easy Connect strings in application configuration when you connect to a single service; they need no client files at all.
Treat tnsnames.ora like code: keep it in version control, change it with a tool or a reviewed edit, and test new aliases with tnsping and a real login before rolling them out. On database servers, remember that database links resolve names there, not on the developer's machine.
Common questions
How do I fix ORA-12154?
Find out which tnsnames.ora and sqlnet.ora the client reads (tnsping shows the parameter files, TNS_ADMIN decides the directory), make sure the alias exists there with balanced parentheses and the right domain, or connect with an Easy Connect string such as host:1521/service to bypass the alias.
tnsping works but my application still gets ORA-12154. Why?
The application probably runs with a different environment: another Oracle home or Instant Client, a service account without TNS_ADMIN, or its own configuration directory. Check the variables and the network/admin directory for the exact process that fails.
What is the difference between ORA-12154 and ORA-12514?
ORA-12154 happens on the client before any connection: the name could not be resolved. ORA-12514 happens later: the client reached a listener, but the listener does not know the service name it was given.
Learn more on CodeWithSQL
Official documentation
- ORA-12154 (Oracle Database Error Messages)
- Troubleshooting Oracle Net Services (Net Services Administrator's Guide 19c)
- Local naming parameters in the tnsnames.ora file (Net Services Reference 19c)
- Parameters for the sqlnet.ora file (Net Services Reference 19c)
Last technically reviewed 24 October 2026; examples and diagnostics run on Oracle Database Error Messages reference (26ai, 21c and 19c); not run locally. Messages and explanations follow Oracle's Database Error Messages reference; no Oracle Database was available, so the examples were not run locally.