Oracle ORA-12154 오류 원인과 해결 방법 완벽 가이드

ORA-12154
2026년 09월 07일 | DBMS Error 가이드

이 글에서 다루는 내용

ORA-12154 에러의 원인 분석, 해결 SQL, 예방 방법을 실무 관점에서 정리합니다.

ORA-12154 TNS: could not resolve the connect identifier specified 는?

ORA-12154 에러는 Oracle 클라이언트가 TNS(Transparent Network Substrate)를 통해 데이터베이스에 접속하려 할 때, 지정한 연결 식별자(Connect Identifier)를 찾지 못할 경우 발생하는 네트워크 구성 오류입니다. 쉽게 말해, 사용자가 입력한 서비스명 또는 TNS 별칭(Alias)이 Oracle 네트워크 설정 파일에 존재하지 않거나, 파일 자체를 읽지 못할 때 이 에러가 발생합니다. DBA 경력 30년 동안 가장 자주 접하는 에러 중 하나로, 개발 환경 구축 초기나 서버 이전 작업 후에 특히 빈번하게 발생합니다.

주요 발생 원인

1. tnsnames.ora 파일 설정 오류 또는 파일 미존재

가장 흔한 원인으로, Oracle 클라이언트가 참조하는 tnsnames.ora 파일에 해당 TNS 별칭이 등록되어 있지 않거나, 파일 자체가 존재하지 않는 경우입니다. 또한 파일이 존재하더라도 ORACLE_HOME 환경 변수가 잘못 설정되어 Oracle이 엉뚱한 경로의 파일을 참조하거나 아예 파일을 찾지 못하는 경우도 매우 많습니다. 실무에서는 여러 Oracle 버전이 동일 서버에 설치된 경우(다중 Oracle Home 환경) 이 문제가 더욱 빈번하게 발생합니다.

2. 잘못된 TNS 별칭 또는 서비스명 오타

연결 문자열에서 사용한 서비스명이나 TNS 별칭이 tnsnames.ora에 등록된 이름과 정확히 일치하지 않는 경우입니다. 대소문자 구분 없이 작동하는 것처럼 보이지만, 특수문자나 공백이 포함된 경우 예상치 못한 불일치가 발생할 수 있습니다. 특히 여러 환경(개발/스테이징/운영)에서 서비스명을 혼용하거나, 복사·붙여넣기 과정에서 보이지 않는 공백이 포함되는 경우가 실무에서 자주 발생합니다.

3. SQLNET.ORA 또는 LDAP.ORA 설정 문제

Oracle Names, LDAP(Directory Service), Easy Connect 등 다양한 네이밍 방식을 사용하는 환경에서 sqlnet.ora 파일의 NAMES.DIRECTORY_PATH 설정이 잘못된 경우 발생합니다. 예를 들어, NAMES.DIRECTORY_PATH = (LDAP, TNSNAMES) 로 설정되어 있으나 LDAP 서버가 응답하지 않거나, ldap.ora 파일 설정이 잘못된 경우 연결 식별자를 해석하지 못해 ORA-12154가 발생할 수 있습니다. 기업 환경에서 Active Directory 연동 Oracle 환경을 사용할 때 특히 자주 나타납니다.

해결 방법

해결 1: tnsnames.ora 파일 확인 및 수정

먼저 현재 Oracle이 참조하는 tnsnames.ora 파일 경로를 확인합니다.

-- SQL*Plus 또는 SQLcl에서 TNS 관련 환경 확인
-- 아래 명령으로 현재 Oracle Home 및 TNS_ADMIN 경로 확인 가능
SELECT name, value
FROM   v$parameter
WHERE  name IN ('db_name', 'service_names', 'instance_name');

운영체제 레벨에서 TNS 경로를 확인하는 방법:

# Linux/Unix 환경
echo $ORACLE_HOME
echo $TNS_ADMIN
cat $ORACLE_HOME/network/admin/tnsnames.ora

# Windows 환경 (CMD)
echo %ORACLE_HOME%
echo %TNS_ADMIN%
type %ORACLE_HOME%\network\admin\tnsnames.ora

tnsnames.ora 파일에 아래와 같이 올바른 형식으로 항목을 추가하거나 수정합니다:

-- tnsnames.ora 올바른 작성 예시
-- 주의: 들여쓰기와 괄호 위치가 중요합니다

MYDB =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCP)(HOST = db-server.example.com)(PORT = 1521))
    (CONNECT_DATA =
      (SERVER = DEDICATED)
      (SERVICE_NAME = MYDB.example.com)
    )
  )

-- RAC 환경의 경우 여러 ADDRESS를 사용합니다
MYDB_RAC =
  (DESCRIPTION =
    (ADDRESS_LIST =
      (ADDRESS = (PROTOCOL = TCP)(HOST = rac-node1)(PORT = 1521))
      (ADDRESS = (PROTOCOL = TCP)(HOST = rac-node2)(PORT = 1521))
    )
    (CONNECT_DATA =
      (SERVER = DEDICATED)
      (SERVICE_NAME = MYDB_SERVICE)
    )
  )

설정 후 tnsping 명령으로 즉시 검증합니다:

# TNS 연결 테스트 (OS 레벨)
tnsping MYDB
tnsping MYDB 10   # 10회 반복 테스트

해결 2: 연결 문자열 직접 지정 (Easy Connect 방식)

tnsnames.ora를 사용하지 않고 Easy Connect 방식으로 직접 연결 정보를 기술하면 ORA-12154를 우회할 수 있습니다.

-- SQL*Plus Easy Connect 방식 (tnsnames.ora 불필요)
-- 형식: //호스트:포트/서비스명
sqlplus scott/tiger@//db-server.example.com:1521/MYDB

-- Python (cx_Oracle / oracledb) Easy Connect 예시
-- dsn = "db-server.example.com:1521/MYDB"

-- JDBC 연결 문자열 예시
-- jdbc:oracle:thin:@//db-server.example.com:1521/MYDB

-- 데이터베이스 링크(DB Link) 생성 시 직접 연결 정보 사용
CREATE DATABASE LINK remote_db
  CONNECT TO remote_user IDENTIFIED BY remote_password
  USING '//db-server.example.com:1521/REMOTEDB';

-- 기존 DB Link 연결 테스트
SELECT * FROM dual@remote_db;

해결 3: sqlnet.ora 네이밍 경로 수정

-- sqlnet.ora 파일 수정 예시
-- 파일 경로: $ORACLE_HOME/network/admin/sqlnet.ora

-- TNSNAMES 방식만 사용하는 경우 (가장 단순하고 안정적)
NAMES.DIRECTORY_PATH = (TNSNAMES, EZCONNECT)

-- LDAP도 함께 사용하는 경우
NAMES.DIRECTORY_PATH = (LDAP, TNSNAMES, EZCONNECT)

-- 현재 sqlnet.ora 설정 확인 쿼리 (DB 내부에서)
SELECT name, value
FROM   v$parameter
WHERE  name LIKE '%dispatchers%'
OR     name = 'local_listener'
OR     name = 'remote_listener';

-- 리스너 상태 확인 (OS 레벨)
-- lsnrctl status
-- lsnrctl services

해결 4: 환경 변수 TNS_ADMIN 명시적 설정

# Linux/Unix: .bash_profile 또는 .bashrc에 추가
export ORACLE_HOME=/u01/app/oracle/product/19.0.0/dbhome_1
export TNS_ADMIN=/u01/app/oracle/product/19.0.0/dbhome_1/network/admin
export PATH=$ORACLE_HOME/bin:$PATH
export LD_LIBRARY_PATH=$ORACLE_HOME/lib:$LD_LIBRARY_PATH

# 설정 적용
source ~/.bash_profile

# Windows: 시스템 환경 변수 설정 (PowerShell)
[System.Environment]::SetEnvironmentVariable("TNS_ADMIN", "C:\oracle\network\admin", "Machine")

예방 방법

1. TNS 구성 파일의 버전 관리 및 변경 이력 관리

tnsnames.ora, sqlnet.ora, listener.ora 등 Oracle 네트워크 구성 파일을 Git 등의 버전 관리 시스템으로 관리하는 것이 Best Practice입니다. 파일 변경 시 반드시 tnsping [서비스명] 명령으로 즉시 검증하는 절차를 팀 내 표준으로 정립하고, 변경 전후 파일을 백업하는 습관을 가져야 합니다. 특히 운영 환경에서는 변경 관리 프로세스(Change Management)를 통해 승인된 변경만 적용하도록 통제해야 합니다.

2. Easy Connect Plus 또는 Oracle Wallet을 활용한 연결 단순화

Oracle 12c 이상에서는 Easy Connect Plus 방식을 활용하거나, Oracle Wallet을 사용하여 TNS 별칭 대신 보안이 강화된 연결 정보 관리 방식을 도입하는 것을 권장합니다. 아래와 같이 Oracle Wallet을 사용하면 tnsnames.ora 의존성을 줄이고 접속 정보를 안전하게 관리할 수 있습니다.

-- Oracle Wallet을 사용한 연결 (mkstore 명령으로 자격증명 저장)
-- 1. Wallet 생성
-- mkstore -wrl /opt/oracle/wallet -create

-- 2. 자격증명 추가
-- mkstore -wrl /opt/oracle/wallet -createCredential MYDB myuser mypassword

-- 3. sqlnet.ora에 Wallet 경로 설정
-- WALLET_LOCATION = (SOURCE = (METHOD = FILE)(METHOD_DATA = (DIRECTORY = /opt/oracle/wallet)))
-- SQLNET.WALLET_OVERRIDE = TRUE

-- 4. Wallet 자격증명으로 연결 (비밀번호 없이 연결 가능)
-- sqlplus /@MYDB

-- Wallet에 저장된 자격증명 목록 확인
-- mkstore -wrl /opt/oracle/wallet -listCredential