ORA-12154: resolve a connect identifier in the actual client environment

Detailed practical guide

Prepare your workspace and inputs

Record the application executable or service, its operating-system identity, Oracle client home and expected service alias. APP_LAB and db.example.invalid below are placeholders; obtain the actual test endpoint and service name from the database owner.

Platform context: Oracle Database 19c client with TNSPING and SQL*Plus; a permitted test service and a test account. SQL*Plus and application client homes may differ.

Scenario to reproduce or investigate

A terminal connects successfully but the application reports ORA-12154. The two processes can read different naming files or use different client libraries, so restarting the database does not repair the client naming decision.

1. Locate the client used in each process context

   Use the branch matching the operating system to identify command resolution and TNS_ADMIN. Compare these observations with the application service environment. Do not assume your interactive PATH proves which library a long-running service has loaded.

   Command, configuration or input

   Linux shell:
   command -v tnsping
   command -v sqlplus
   printenv TNS_ADMIN
   
   Windows Command Prompt:
   where tnsping
   where sqlplus
   echo %TNS_ADMIN%

   Expected result · ผลที่ควรเห็น

   The record names the actual application client configuration and notes any difference from the successful terminal.

   If it fails · เมื่อไม่ผ่าน

   If the app uses JDBC thin or another client without TNSPING, use that driver’s documented naming configuration instead; do not force an unrelated Oracle home onto the application.

2. Resolve the exact alias and inspect the attempted descriptor

   Run TNSPING from the matching client environment. Record the naming method, configuration file and attempted descriptor shown by that installed client. If local naming is intended, correct only the alias in the actual tnsnames.ora copy after preserving it. The example descriptor is illustrative and cannot connect until approved values replace the placeholders.

   Command, configuration or input

   tnsping APP_LAB
   
   Example tnsnames.ora entry:
   APP_LAB =
     (DESCRIPTION =
       (ADDRESS = (PROTOCOL = TCP)(HOST = db.example.invalid)(PORT = 1521))
       (CONNECT_DATA = (SERVICE_NAME = app_lab.example.invalid))
     )

   Expected result · ผลที่ควรเห็น

   The client resolves APP_LAB to the owner-confirmed host, port and SERVICE_NAME. A new network or listener error means naming progressed to a different layer.

   If it fails · เมื่อไม่ผ่าน

   If ORA-12154 remains, check exact alias spelling, syntax, active TNS_ADMIN and configured naming methods. If TNSPING reports a listener problem, follow that problem separately rather than repeatedly editing the alias.

3. Prove authentication and application recovery separately

   Connect with SQL*Plus using a password prompt rather than putting a password in command history. Run only a read-only confirmation and repeat the actual application operation under its own identity and environment. A TNSPING OK result is not a database login test.

   Command, configuration or input

   sqlplus -L app_test@APP_LAB
   
   After the password prompt, in SQL*Plus:
   SELECT SYS_CONTEXT('USERENV','SERVICE_NAME') FROM dual;
   EXIT

   Expected result · ผลที่ควรเห็น

   The login reaches the approved service and the original application operation succeeds using the corrected naming configuration.

   If it fails · เมื่อไม่ผ่าน

   An authentication error belongs to the account or authentication layer; do not change the service descriptor to bypass it. If only SQL*Plus works, compare application environment and loaded driver settings again.

Recovery and cleanup

Retain the original naming file and exact environment values. Restore only the changed client configuration if the correction breaks other supported aliases; database restart is not part of this naming-only procedure.

Apply to actual work and known limits

Use the actual Oracle client type and service-owner values. This guide is for a client alias-resolution failure; it does not validate another driver’s TLS wallet, authentication or service registration.

Authored against the cited documentation. Execution on the stated vendor product or physical equipment remains to be verified.