Getting this error when connecting to Oracle? It means SQL Developer can't find the database alias in your TNS configuration. Here's how to fix it.
# Error classification
error_code = ORA-12154
error_class = Oracle TNS / naming
message = TNS:could not resolve the connect identifier specified
# Where Oracle looks
config_file = tnsnames.ora
env_var = TNS_ADMIN # points to network/admin dir
also_checked = sqlnet.ora (NAMES.DIRECTORY_PATH)
fastest_fix = switch connection type to Basic
time_to_fix = 5 to 15 minutes
difficulty = Intermediate
// see "Quickest Fix" below for fastest path
Understanding the error.
This error occurs when Oracle can't find the TNS alias (database name) you're trying to connect to. Oracle looks for this alias in the tnsnames.ora file, and either:
Skip TNS entirely — connect directly using hostname, port, and service name. This bypasses tnsnames.ora completely.
In the Connections panel on the left side of the IDE, click the green + icon at the top of the panel header. The "New / Select Database Connection" dialog opens. In its left-side tab strip, click Oracle if not already selected.
Mid-dialog, find the "Connection Type" dropdown (first selector after Username/Password). Change it from TNS to Basic. The form below swaps from a "Network Alias" picker to direct Hostname/Port/Service Name inputs.
Fields top-to-bottom:
Hostname: Oracle server FQDN or IP (e.g., db.example.com)
Port: 1521 (default; change only if DBA confirmed)
Service name: e.g., ORCL, XE, or your PDB name like ORCLPDB1 — select the Service name radio, not SID
Click Test (bottom-left). Status should show Status: Success in green. Then Save → Connect.
Four checks to fix your TNS configuration so the alias resolves.
# SQL Developer needs to know where to find tnsnames.ora
# Windows
setx TNS_ADMIN "C:\oracle\network\admin"
# Linux / macOS
export TNS_ADMIN=/opt/oracle/network/admin
// Or in SQL Developer:
// Tools → Preferences → Database → Advanced → Tnsnames Directory
# A correct tnsnames.ora entry looks like this:
MYDB =
(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = myserver.com)(PORT = 1521))
(CONNECT_DATA =
(SERVER = DEDICATED)
(SERVICE_NAME = orcl)
)
)
// Common mistakes: missing parentheses, wrong indentation,
// spaces in alias name, SID used instead of SERVICE_NAME
# The connection name in SQL Developer must match the alias
# in tnsnames.ora exactly. TNS aliases are case-insensitive,
# but watch for:
issue_1 = extra spaces before/after the name
issue_2 = typos (PROD vs PRDO)
issue_3 = wrong environment (DEV vs PROD)
# From command line, test if the TNS alias resolves
$ tnsping MYDB
// If tnsping fails, the problem is in your TNS configuration,
// not SQL Developer.
Less common but possible issues if the standard fixes don't apply.
sqlnet.ora for the NAMES.DIRECTORY_PATH setting. It should include TNSNAMES.If the Basic connection workaround and the four TNS checks above didn't help, your Oracle DBA can confirm the LDAP / TNSNAMES naming setup and the SQLNET configuration at the server level — usually a 5-minute fix once they look.
See also: Connection Refused · Access Denied · Download SQL Developer