// Oracle error reference

ORA-12154: TNS: could not resolve the connect identifier

The Oracle client couldn't turn the name you connected with into a database address: the alias isn't in tnsnames.ora, or the client is reading a different file.

Error code
ORA-12154
Category
Connection and login
Error message
TNS:could not resolve the connect identifier specified

What it means

When you connect with a net service name such as SALES, the Oracle client looks it up with its naming methods, usually tnsnames.ora. ORA-12154 means it couldn't find that name. The database is never contacted, so the server isn't the problem.

Newer releases word it as Cannot connect to database. Cannot find alias alias_value in repository_loc., which also says where the client looked.

Common causes

  • The alias isn't defined in the tnsnames.ora the client actually reads, or it's misspelled.
  • TNS_ADMIN points at another directory, or several Oracle homes each have their own tnsnames.ora.
  • A syntax error in tnsnames.ora, such as unbalanced parentheses, that makes the entry unreadable.
  • sqlnet.ora restricts naming methods (NAMES.DIRECTORY_PATH) so tnsnames.ora isn't consulted.
  • A domain is appended to the name from NAMES.DEFAULT_DOMAIN and the entry doesn't have it.

How to fix it

  1. Skip the alias and connect with Easy Connect, which needs no tnsnames.ora: sqlplus app_user@//db-host:1521/salespdb.

  2. Check which file the client uses: run tnsping SALES, which prints the parameter file it read and how it resolved the name.

  3. Add or fix the entry in that file.

    SALES =
      (DESCRIPTION =
        (ADDRESS = (PROTOCOL = TCP)(HOST = db-host)(PORT = 1521))
        (CONNECT_DATA = (SERVICE_NAME = salespdb)))
  4. Set TNS_ADMIN to the directory that holds the right tnsnames.ora and sqlnet.ora.

Related errors

More connection and login errors

The code and message text are from the Oracle Database Error Help. Browse the full Oracle error list or search every database error.

// fewer errors, faster fixes

Work on Oracle in SQLly

A native SQL client for macOS, Windows and Linux with schema-aware IntelliSense, guardrails for risky statements and clear error messages, for Oracle and the other databases you use.