Loading

Oracle Connection Fails With ORA-12154, ORA-17868 or "The Network Adapter Could Not Establish the Connection" When Using an LDAP (ldap.ora) Net Service Name

Julkaisupäivä: Oct 14, 2026
Kuvaus

When you enter an Oracle net service name (alias) in the Server field of the Oracle connector. The alias is resolved by LDAP directory naming (ldap.ora, plus NAMES.DIRECTORY_PATH=(LDAP, ...) in sqlnet.ora). The connection fails with one of these errors:

Error 1
ORA-12154: Cannot connect to database. Could not find alias <alias> in <folder>/tnsnames.ora. Unable to connect to the Oracle server "<alias>". Check that the server is running and that you have access privileges to the requested database.
 
Error 2
IO Error: The Network Adapter could not establish the connection (CONNECTION_ID=...) Unable to connect to the Oracle server "<alias>". Check that the server is running and that you have access privileges to the requested database.
 
Error 3
ORA-17868: Unknown host specified.: No such host is known (<alias>)
 
You may also notice:
  • On the same machine, the alias works in Oracle tools such as SQL*Plus, SQL Developer (OCI/thick mode) or tnsping.
  • An alias defined in tnsnames.ora connects without problems.
  • The Tableau log (jprotocolserver) shows java.net.UnknownHostException: No such host is known (<alias>). The connection string uses the alias as the host name:
Connecting to jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=<alias>)(PORT=<port>))(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=...))) ... Caused by: java.net.UnknownHostException: No such host is known (<alias>)
 
Environment
  • Tableau Desktop
  • Tableau Server
  • Tableau Bridge
  • Oracle connector using the Oracle JDBC driver (ojdbc8.jar, ojdbc11.jar)
  • Oracle net service names stored in an LDAP directory (OID / OUD) and configured through ldap.ora
  • Windows and Linux
Cause
The Oracle connector connects through the Oracle JDBC Thin driver.
  • The driver looks up net service names in tnsnames.ora, in the folder set by oracle.net.tns_admin in the oracle.properties file.
  • Oracle documents LDAP lookups for this driver only when the LDAP server is given inside the connection URL. Tableau doesn't use ldap.ora or NAMES.DIRECTORY_PATH for the Oracle connector.
  • Oracle Client (OCI) tools such as SQL*Plus and tnsping do read those files. This is why the alias works there and not in Tableau.
  • If the alias isn't in tnsnames.ora, Tableau treats the Server value as a host name. DNS can't resolve it, so you see UnknownHostException or ORA-17868.

Installing the Oracle Client on the machine does not change this. When the Oracle JDBC driver is in the Tableau Drivers folder, the Oracle connector uses JDBC.
Ratkaisu
Use one of the options below. Option 1 keeps the connection details in LDAP.
Option 1: Use Other Databases (JDBC) with an LDAP connection URL
The Oracle JDBC driver can look up a net service name in LDAP when the LDAP server is given inside the connection URL.
Step 1: Build the LDAP URL from your ldap.ora file
Open the ldap.ora file your Oracle tools use (usually in <ORACLE_HOME>/network/admin or your TNS_ADMIN folder). It looks like this:
DIRECTORY_SERVERS = (ldap1.example.com:389:636, ldap2.example.com:389:636)
DEFAULT_ADMIN_CONTEXT = "dc=example,dc=com"
DIRECTORY_SERVER_TYPE = OID
 
Use those values to build the URL:
jdbc:oracle:thin:@ldap://<ldap_host>:<ldap_port>/<net_service_name>,cn=OracleContext,<DEFAULT_ADMIN_CONTEXT>
 
Example:
jdbc:oracle:thin:@ldap://ldap1.example.com:389/SALES,cn=OracleContext,dc=example,dc=com
Note: If your directory doesn't allow anonymous access, ask your DBA for the bind settings. Name matching in the URL can also be case-sensitive.
 
Step 2: Connect in Tableau Desktop

  1. Select Connect > To a Server > More... > Other Databases (JDBC).
  2. In URL, paste the LDAP URL from Step 1.
  3. Set Dialect to Oracle.
  4. Enter the database Username and Password.
  5. Select Sign In.

 

Option 2: Add the net service name to tnsnames.ora
Use this option if users must keep the Oracle connector and type a short alias.

  1. On a machine where the alias works, run:tnsping <alias>The output shows the full connect descriptor after Attempting to contact, for example:(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=db01.example.com)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=sales.example.com)))
  2. Add an entry to a tnsnames.ora file:SALES =
      (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=db01.example.com)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=sales.example.com)))
  3. Point Tableau to the folder with tnsnames.ora using oracle.properties, as described in Setting an Oracle Connection to Use TNSNames.ora.
  4. In the Oracle connector, enter the alias (SALES) in Server.

Note: tnsnames.ora is a static copy. If the DBA changes the entry in LDAP, update tnsnames.ora too.
 
Option 3: Enter the host, port and service name directly
In the Oracle connector, enter:

  • Server: the database host name (not the alias), for example db01.example.com
  • Service: the service name, for example sales.example.com
  • Port: the listener port, for example 1521
    Get these values from your DBA or from the tnsping output in Option 2.

 

Frequently asked questions
Why do SQL*Plus and tnsping work, but Tableau does not?
They use the Oracle Client (OCI), which reads ldap.ora and sqlnet.ora. Tableau's Oracle connector uses the JDBC Thin driver, which doesn't use those files for name lookups.

Will installing the full Oracle Client fix it?
No. When the Oracle JDBC driver is in the Tableau Drivers folder, the Oracle connector uses JDBC.

Does putting ldap.ora in the same folder as tnsnames.ora (oracle.properties) help?
No. The JDBC driver only reads tnsnames.ora from that folder.

Do I need to add my alias to ldap.ora?
No. ldap.ora doesn't contain aliases. It only says where the LDAP server is (DIRECTORY_SERVERS) and where to search (DEFAULT_ADMIN_CONTEXT). The alias entries are stored in the LDAP directory itself.

Does this affect Tableau Bridge?
Yes. Bridge uses the same Oracle connector, so the same options apply on each Bridge machine.
Knowledge-artikkelin numero

005461848

 
Ladataan
Salesforce Help | Article