Setting an Oracle Connection to Use TNSNames.ora or LDAP.ora

Published: 29 Nov 2016
Last Modified Date: 18 Mar 2021


How to set an Oracle connection to use TNSNames.ora or LDAP.ora.

Benefits to setting up TNSNames.ora or LDAP.ora connections.

The following common Oracle errors can be corrected or avoided by setting up your data connection to use TNSNames.ora or LDAP.ora.
  • ORA-12154: TNS: could not resolve the connect identifier specified

  • ORA-12514: TNS listener does not currently know of service requested in connect descriptor

  • ORA-12541: TNS: no listener

  • ORA-12170: TNS:Connect timeout occurred

  • ORA-12504: TNS listener was not given the SERVICE_NAME in CONNECT_DATA


  • Tableau Desktop
  • Tableau Server
  • Oracle


Tableau Desktop and/or Server On Windows, OCI Client

Step 1: Set the TNS_Admin environment variable.

  1. Select Start > Control Panel > System 
  2. Select Advanced System Settings
  3. In the System Properties dialog box, on the Advanced tab, select Environment Variables. 
  4. Under System Variables, click New. 
  5. In the New System Variable dialog box, enter the following, then click OK: 
    • Variable name: TNS_ADMIN 
    • Variable value: the directory containing the TNSNames.ora file.
  6. Click OK in the Environment Variables dialog box and the System Properties dialog box. 
  7. Restart your computer to ensure that the new variable is recognized. 

Step 2: Use the Oracle net service name to connect to Oracle in Tableau. 

  1. Close all open Tableau workbooks and open a new instance of Tableau.
  2. In Tableau Desktop, select Connect to Data > Oracle.
    • For Server, enter the oracle 'net_service_name' recorded in the TNSNAmes.ora file.
    • Enter username and password as appropriate.

The rest of the connection details from the TNSNames.ora file are communicated through the TNS_ADMIN system variable. Note that you should leave the optional service name and port information empty, otherwise it may interfere with the connection by duplicating information.

Tableau Desktop and Server 2020.2 and above, Windows, JDBC Driver
Create an file containing the following text (Example):\\Oracle_Client\\network\\admin

Change the path if necessary to reference the location of the tnsnames.ora file within the host file system. The double backslashes \\ are intentional and required even though the \\ paths will not work if copied and pasted directly into windows file explorer. The file will only function properly with double backslashes in this context.

Place the file in the following location:
Desktop: Documents\My Tableau Repository\Datasources 
Server: C:\ProgramData\Tableau\Tableau Server\data\tabsvc\vizqlserver\Datasources (or equivalent path if alternate install location employed). Be sure to create the folder if it doesn't already exist.

Server only: Once the files and folders have been created, ensure the run as user is provided with appropriate permissions to the file and restart Tableau Server.

Further information regarding JDBC properties files may be found here:
On Mac

Step 1:

  1. Close Tableau Desktop if it is open. 
  2. Ensure that you have downloaded and installed the Oracle drivers for Mac from Tableau's Drivers page.
  3. Copy an existing LDAP.ora or TNSNames.ora file containing connection information to /etc: 
  • In Finder, select Go > Go To Folder, and then type /etc.
  • Copy the .ora file to /etc.

Step 2: Configure the TNS_ADMIN environment variable 

  1. Start Terminal and type the following command:

    sudo nano /etc/launchd.conf

    Note: Nano is a text-based editor that is always available on Mac computers.

  2. Type your password when prompted.

  3. Type the following:

    launch setenv TNS_ADMIN /etc

  4. Press Ctrl-X, then Y, then Enter to save changes and exit nano.
  5. Restart your Mac.

Step 3: Verify that the TNS_ADMIN variable was set: 

  1. Start Terminal and type the following command:


  2. You will see a list of all system variables. Look for:

    declare -x TNS_ADMIN="/etc"

  3. Confirm that DNS resolution is working for the host name listed in the .ora file by pinging the host name in Terminal or Network Utility. Use a fully-qualified domain name, such as, instead of a simple server name. 
You should now be able to start Tableau Desktop on your Mac and connect to the Oracle database, providing only the server name from the TNSNames.ora or LDAP.ora file. 
On Linux

Summary of Steps:

  1. Copy the tnsnames.ora file to a location the tableau user has access to
  2. Set permissions on the file.
  3. Update the environment TNS_ADMIN variable, if needed, to point to the directory from step (1).

Step 1: Copy the tnsnames.ora file to a directory the unprivileged user (tableau) can access

For versions 2019.3.x and up:
Copy the tnsnames.ora file to the /etc directory.
For versions 2019.2.x and earlier:
By default, the unprivileged user is named 'tableau'. All Tableau Server processes are run with this account, and it must be able to locate the tnsnames.ora file to use it.
If you have already installed the Oracle connector, we recommend you copy the file to the directory /opt/tableau/tableau_driver/oracle.
You can confirm that the directory is accessible by the user by using 'su' to change to the account and changing to the directory. For example:
sudo su tableau
cd /opt/tableau/tableau_driver/oracle
If these steps result in a 'permission denied' error, you need to update the permissions on the directory you are using.

Step 2: Set permissions for the tnsnames.ora file

2019.2.x and earlier, follow the steps below:
  1. Navigate to the file path where the tnsnames.ora file is located.
  2. Grant permissions to the file by running the command: chmod 666 tnsnames.ora
  3. Verify file permissions with the following command: ls -l
Note: The environment path should not have a trailing slash. If the format of the path is incorrect, users may encounter an ORA-12154 error.

2019.3 and later:
Place the tsnames.ora file in the /etc directory on the Linux machine. No environmental variable is necessary.

2020.2 and later:

Create an /var/opt/tableau/tableau_server/data/tabsvc/vizqlserver/Datasources/ file with below text:


Change the /etc if necessary to point to the path of the tnsnames.ora file within the file system on your Server.

Further information regarding JDBC properties files may be found here:

Step 3: Set the TNS_ADMIN environment variable to point to the directory from step (1)

For versions 2019.3.x and up: you can skip this step; no environment variable is required.
For versions 2019.2.x and earlier:
  1. In a text editor, open the file that matches your version of Tableau Server:
    • Tableau Server 10.5.x -- /etc/systemd/system/tabsvc_0.service
    • ​​Tabelau Server 2018.1.x - 2019.2 --  /var/opt/tableau/tableau_server/.local/share/systemd/user/tabsvc_0.service
  2. Add the following line, where "/path/to/file-folder" is the directory you copied tnsnames.ora to in step 1:
    • Environment=TNS_ADMIN=/path/to/file-folder
  3. Save the changes to the file.

Note: The environment path should not have a trailing slash; if the format of the path is incorrect, users may encounter an ORA-12154 error.

All environments

Optional steps

Finding tnsnames.ora files

If the Oracle client is installed on your server, the tnsnames.ora file will be located in the following directory: $ORACLE_HOME/network/admin.
You can verify if this file exists with the following commands:

will print the file path.

sudo find / -iname tnsnames.ora
 will list the locations of any tnsnames.ora files in your file system.

Note: It is not necessary to have the Oracle client installed to use tnsnames.ora with Tableau Server. This step is simply to help you work with any existing installation.

Creating new tnsnames.ora file from scratch

If no tnsnames.ora file is present on this computer, and you do not have one to copy up from a client workstation, you can create one using a text editor. Keep in mind the following restrictions:

  • The tnsnames.ora file name is case sensitive, and must be in all lower-case letters. 

  • The file should not use tab-spacing.

Below is a potential template for an entry. Elements in brackets must be replaced by values obtained from your database administrator.
Note: Although a TNSNames.ora file on a Windows or Mac computer may not require the ADDRESS_LIST entry, the tnsnames.ora file on a Linux computer requires this variable.


For example: 

Production =
    (ADDRESS = (PROTOCOL = TCP)(HOST = = 1521)
    (SERVICE_NAME = orcl)


Additional Information

Additional configuration steps if you have SSL configured on Oracle

Configuring ORACLE_HOME and TNS_ADMIN for Oracle (With SSL configured on Oracle)

sudo su -l tableau
      touch /var/opt/tableau/tableau_server/.config/systemd/tableau_server.conf.d/oracle.conf
      echo "ORACLE_HOME=/u01/app/oracle/product/12.1.0/client_1" | tee -a /var/opt/tableau/tableau_server/.config/systemd/tableau_server.conf.d/oracle.conf
      echo "TNS_ADMIN=/u01/app/oracle/product/12.1.0/client_1/network/admin" | tee -a /var/opt/tableau/tableau_server/.config/systemd/tableau_server.conf.d/oracle.conf 
      chmod 744 /var/opt/tableau/tableau_server/.config/systemd/tableau_server.conf.d/oracle.conf

cd /opt/tableau/tableau_server/packages/scripts.near.xx.xxxx.xxxx/
            sudo ./stop-administrative-services
            sudo ./start-administrative-services
source /etc/profile.d/

Discuss this article... Feedback Forum
Did this article resolve the issue?