ORA-12154: TNS could not resolve, explained and fixed

ORA-12154: TNS:could not resolve the connect identifier specified happens before any network traffic: the Oracle client took the name you gave it (the part after the @, or the service name in a connection string) and could not find a matching entry in its naming configuration, usually tnsnames.ora. Either the alias is not in the file the client actually reads, the entry's syntax is broken, or name resolution is configured to use a method (like a directory server) that does not hold the name. The database server is uninvolved and may be perfectly healthy.

The checks, in order

  1. Test resolution directly: tnsping ALIAS reports which configuration files the client used (it prints the parameter file path) and whether the alias resolves to an address. That printed path is the single most valuable clue: it is frequently not the file you have been editing.
  2. Find which tnsnames.ora is authoritative: the client searches the directory named by the TNS_ADMIN environment variable first, then the Oracle home's network/admin, then (for some tools) the current directory. Multiple Oracle homes (a database install plus a separate client plus an IDE's bundled client) mean multiple candidate files; edit the one tnsping names.
  3. Inspect the entry itself: the alias must match exactly, and the entry's parentheses must balance; a syntax error in any entry can poison the file's parsing. A minimal valid entry is: ALIAS = (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = dbhost)(PORT = 1521)) (CONNECT_DATA = (SERVICE_NAME = svc))).
  4. Check sqlnet.ora's NAMES.DIRECTORY_PATH: if it lists only LDAP or EZCONNECT and not TNSNAMES, the file will never be consulted. Add TNSNAMES to the list, or connect with the EZCONNECT form (host:port/service) which needs no file entry at all and is an excellent test of whether the database itself is reachable.

Common questions

tnsping works but my application still gets 12154, why? The application uses a different Oracle client (a bundled JDBC thin driver reads no tnsnames at all by default; an OCI-based tool uses its own home; a 32-bit application has its own client). Each stack resolves names its own way; configure the one the failing application actually uses, or give it a full connection string.

Does JDBC use tnsnames.ora? The thin driver does not, unless configured with a TNS_ADMIN property and the corresponding settings; the common JDBC form embeds host, port, and service directly in the URL. A 12154 in a Java application usually comes from an OCI driver or a framework configured to use TNS aliases.

I edited tnsnames.ora and nothing changed, what gives? Almost always the client is reading a different file (TNS_ADMIN points elsewhere, or there are multiple homes), or the running process cached its environment at start. tnsping's printed parameter-file path settles which file is real.

Related errors

ORA-01017: invalid username/password · ORA-00942: table or view does not exist · MySQL error 2002 (cannot connect)