ORA-12154는 Oracle 클라이언트가 사용자가 입력한 접속 별칭(예: ORCL, PROD)을 실제 호스트·포트·서비스명 조합으로 매핑하지 못했을 때 발생한다. 네트워크 끊김이나 리스너 장애가 아니라 "어디로 가야 하는지조차 모르는" 이름 해석(name resolution) 단계의 실패다. 운영 서버가 잘 살아 있어도 클라이언트의 tnsnames.ora 한 줄이 어긋나면 즉시 마주치는 에러이며, 여러 ORACLE_HOME이 설치된 PC에서는 빈번하게 발생한다. 본 글은 ORA-12154의 정확한 의미, Oracle Net의 네 가지 이름 해석 방법, TNS_ADMIN 우선순위, 일곱 가지 원인, 진단 명령, 그리고 tnsnames.ora·sqlnet.ora 설정 패턴까지 정리한다.
주요 원인 ／ tnsnames.ora 별칭 누락·오타, TNS_ADMIN 경로 오류, 잘못된 ORACLE_HOME, NAMES.DIRECTORY_PATH 설정, EZConnect 문법 오류, 인코딩 문제
근본 해법 ／
tnsping으로 해석 검증, TNS_ADMIN 명시, EZConnect 활용, sqlnet.ora 순서 점검목차
ORA-12154는 이름 해석(name resolution) 단계의 실패다. Oracle 클라이언트는 사용자가 입력한 "ORCL", "PROD" 같은 별칭을 보고 실제 통신 대상(호스트:포트:서비스명)으로 변환하는 과정이 필요하다. 이 변환은 네트워크 통신이 일어나기 전에 클라이언트 측에서 완전히 끝난다. ORA-12154가 발생했다는 것은 클라이언트가 "어디로 연결해야 할지조차 모르는 상태"라는 뜻이다.
이 점이 ORA-12541("리스너 없음"), ORA-12514("서비스 미등록"), ORA-12170("연결 타임아웃") 같은 다른 TNS 에러와 결정적으로 다르다. 다른 에러들은 어디로 가야 할지는 알았지만 그 다음 단계에서 실패한 경우다.
1. Oracle Net 이름 해석 흐름
Oracle 클라이언트가 별칭을 해석하는 과정은 다음과 같다.
- sqlnet.ora 읽기 ━
NAMES.DIRECTORY_PATH파라미터로 시도할 해석 방법 순서 결정 - 방법별 시도 ━ Oracle 기본 순서는 TNSNAMES → LDAP → EZCONNECT (sqlnet.ora에서 재정의 가능)
- 첫 성공한 방법 채택 ━ 성공 시 호스트:포트:서비스명 추출
- 전부 실패 시 ORA-12154 ━ 모든 방법이 실패하면 발생
여기서 핵심은 TNS_ADMIN 환경 변수다. Oracle은 sqlnet.ora, tnsnames.ora를 찾을 때 다음 우선순위로 디렉토리를 결정한다.
TNS_ADMIN환경 변수 (있다면 최우선)- Windows 레지스트리
HKLM\SOFTWARE\ORACLE\KEY_xxx\TNS_ADMIN $ORACLE_HOME/network/admin(마지막 기본값)
여러 ORACLE_HOME이 설치된 환경에서는 어느 홈의 admin 디렉토리를 보고 있는지가 가장 큰 함정이다.
2. Oracle Net 네 가지 이름 해석 방법
방법 1 ／ Local Naming (tnsnames.ora)
가장 일반적이고 직관적인 방식이다. 클라이언트의 tnsnames.ora 파일에 별칭별 접속 정보를 직접 기록한다.
-- tnsnames.ora 예시
ORCLPDB =
(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = db.example.com)(PORT = 1521))
(CONNECT_DATA =
(SERVER = DEDICATED)
(SERVICE_NAME = orclpdb1)
)
)방법 2 ／ EZConnect
파일 없이 한 줄로 모든 정보를 표현한다. 호스트:포트/서비스명 형식이다.
# 기본 형식
sqlplus user/pass@dbhost:1521/orclpdb
# 포트 생략 가능 (기본 1521)
sqlplus user/pass@dbhost/orclpdb
# Easy*Plus 인스턴트 클라이언트에서도 동일
sqlplus scott/tiger@//192.168.1.10:1521/ORCL방법 3 ／ Directory Naming (LDAP)
OID(Oracle Internet Directory) 또는 MS Active Directory에 별칭 정보를 중앙 등록한다. 대규모 환경에서 사용한다. ldap.ora 설정이 필요하다.
방법 4 ／ External Naming
NIS 같은 외부 네이밍 서비스를 활용한다. 현재는 거의 사용되지 않는다.
3. 발생 원인 일곱 가지
원인 1 ／ tnsnames.ora 별칭 누락·오타
가장 흔한 원인이다. 별칭이 없거나, 대소문자·도메인 접미사가 미세하게 다른 경우다. 클라이언트가 ORCL.WORLD를 찾는데 파일에 ORCL만 있으면 해석에 실패한다.
원인 2 ／ TNS_ADMIN 경로 오류
TNS_ADMIN 환경 변수가 잘못된 디렉토리를 가리키거나, 의도와 다른 경로를 가리키는 경우다. PC를 재부팅하지 않은 채 환경 변수를 변경했을 때 일부 프로세스만 새 값을 반영하는 경우도 있다.
원인 3 ／ 잘못된 ORACLE_HOME
PC에 여러 ORACLE_HOME이 설치된 환경에서 PATH에 먼저 잡히는 홈이 의도와 다른 경우다. SQL*Plus는 12c 인스턴트 클라이언트의 admin을 보고 있는데 PL/SQL Developer는 11g 풀 클라이언트의 admin을 보는 식의 충돌이 흔하다.
원인 4 ／ sqlnet.ora NAMES.DIRECTORY_PATH
NAMES.DIRECTORY_PATH에서 TNSNAMES가 빠져 있으면 tnsnames.ora를 절대 읽지 않는다. 누군가 LDAP만 사용하도록 변경했다가 LDAP 설정이 불완전한 경우가 대표적이다.
# sqlnet.ora 정상 예시
NAMES.DIRECTORY_PATH = (TNSNAMES, EZCONNECT, LDAP)
# 문제: TNSNAMES 누락 → 파일을 안 읽음
NAMES.DIRECTORY_PATH = (LDAP)원인 5 ／ EZConnect 문법 오류
EZConnect 사용 시 슬래시·콜론 누락, 호스트명 오타가 흔하다. host:1521orclpdb처럼 슬래시가 빠지면 클라이언트가 별칭으로 해석하려다 실패한다.
원인 6 ／ tnsnames.ora 인코딩·구문 오류
괄호 불일치, BOM(Byte Order Mark)이 포함된 UTF-16 인코딩, 탭과 공백 혼입 등으로 파싱이 실패한다. 메모장에서 저장한 파일이 종종 BOM이 들어간 UTF-8로 변환되어 문제를 일으킨다.
원인 7 ／ LDAP/OID 미스컨피규레이션
LDAP를 사용하는데 ldap.ora가 없거나, DEFAULT_ADMIN_CONTEXT가 잘못 설정된 경우다. 별칭 해석은 LDAP 디렉토리 검색에 의존하므로 LDAP 서버 자체가 응답하지 않으면 즉시 실패한다.
4. 재현과 진단
재현
ORA-12154는 의도적으로 잘못된 별칭을 사용하면 즉시 재현된다.
# 존재하지 않는 별칭
sqlplus scott/tiger@WRONG_ALIAS
# ERROR: ORA-12154: TNS:could not resolve
# the connect identifier specified
# tnsping으로도 동일하게 확인
tnsping WRONG_ALIAS
# TNS-03505: Failed to resolve name진단 명령
ORA-12154가 발생하면 다음 명령을 순서대로 실행한다.
# Linux/Mac 환경변수 확인
echo $TNS_ADMIN
echo $ORACLE_HOME
which sqlplus
# Windows 환경변수 확인
set TNS_ADMIN
set ORACLE_HOME
where sqlplus
# tnsnames.ora 위치 확인
ls -la $TNS_ADMIN/tnsnames.ora # Linux
dir %TNS_ADMIN%\tnsnames.ora # Windows
# 별칭 해석 단독 검증 (네트워크 미접속 OK)
tnsping ORCLPDB
# sqlplus로 EZConnect 우회 시도
sqlplus user/pass@//db.example.com:1521/orclpdb1tnsping이 성공하지만 sqlplus가 실패하면 별칭 해석은 OK이고 다른 단계(리스너·인증)에서 실패한 것이다. tnsping도 실패하면 순수한 ORA-12154 상태다.
5. tnsnames.ora·sqlnet.ora 표준 작성
tnsnames.ora 권장 형식
# 단일 인스턴스
ORCLPDB =
(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = db.example.com)(PORT = 1521))
(CONNECT_DATA =
(SERVER = DEDICATED)
(SERVICE_NAME = orclpdb1)
)
)
# RAC (다중 노드 + LOAD_BALANCE)
PROD_RAC =
(DESCRIPTION =
(ADDRESS_LIST =
(LOAD_BALANCE = on)
(FAILOVER = on)
(ADDRESS = (PROTOCOL = TCP)(HOST = scan-host.example.com)(PORT = 1521))
)
(CONNECT_DATA =
(SERVER = DEDICATED)
(SERVICE_NAME = prod_svc)
)
)sqlnet.ora 권장 형식
# 해석 순서: tnsnames → EZConnect → LDAP
NAMES.DIRECTORY_PATH = (TNSNAMES, EZCONNECT, LDAP)
# 도메인 자동 추가 비활성 (별칭 오타 추적이 쉬워짐)
NAMES.DEFAULT_DOMAIN =
# 연결 타임아웃 (선택)
SQLNET.OUTBOUND_CONNECT_TIMEOUT = 106. 해결 방법
패턴 A ／ TNS_ADMIN 명시 설정
여러 ORACLE_HOME 환경에서는 TNS_ADMIN을 명시적으로 설정해 한 디렉토리로 통일한다.
# Linux/Mac (.bashrc 또는 .zshrc)
export TNS_ADMIN=/etc/oracle
# Windows (사용자 환경변수)
setx TNS_ADMIN "C:\oracle\network\admin"패턴 B ／ EZConnect 우회
별칭 설정이 어려운 환경(컨테이너·CI·임시 진단)에서는 EZConnect로 우회한다. 파일 없이 연결할 수 있다.
# 호스트:포트/서비스명 직접 지정
sqlplus scott/tiger@//db.example.com:1521/orclpdb1
# Python cx_Oracle
import cx_Oracle
conn = cx_Oracle.connect('scott', 'tiger',
'db.example.com:1521/orclpdb1')
# JDBC
jdbc:oracle:thin:@//db.example.com:1521/orclpdb1패턴 C ／ 설정 파일 통합 관리
운영 환경에서는 모든 클라이언트가 같은 tnsnames.ora를 사용하도록 중앙 관리한다. 공유 NFS, 형상 관리 시스템, 또는 자동 배포 도구로 한 곳에서 관리하는 마스터 파일을 배포한다. 별칭 변경 시 모든 노드에 동시에 반영된다.
패턴 D ／ LDAP 중앙화 (대규모)
500대 이상의 클라이언트가 있다면 OID 또는 AD에 별칭을 등록하고 sqlnet.ora의 NAMES.DIRECTORY_PATH 첫 번째에 LDAP를 둔다. tnsnames.ora 파일 배포 자체가 사라진다.
7. ORA-12154·12541·12514·12545·12170 구분
다섯 가지 TNS 에러는 단계별로 명확히 다른 의미를 갖는다.
| 에러 코드 | 실패 단계 | 의미 |
|---|---|---|
| ORA-12154 | 이름 해석 | 별칭 → 호스트:포트:서비스 매핑 실패 |
| ORA-12545 | 호스트 DNS 해석 | 호스트명이 IP로 변환되지 않음 |
| ORA-12170 | TCP 연결 | 호스트는 알지만 라우팅·방화벽으로 연결 타임아웃 |
| ORA-12541 | 리스너 응답 | 호스트에 도달했으나 리스너가 죽었거나 포트 응답 없음 |
| ORA-12514 | 서비스 등록 | 리스너는 살아있지만 요청한 SERVICE_NAME을 모름 |
핵심은 단계별로 다르다는 점이다 ━ 12154는 가장 빠른 실패(클라이언트 내부), 12545·12170은 네트워크 단계, 12541·12514는 서버 응답 단계.
대부분 다른 디렉토리의 tnsnames.ora를 보고 있기 때문이다. TNS_ADMIN, ORACLE_HOME을 출력해 어느 admin 디렉토리를 보는지 먼저 확인한다. SQL*Plus와 IDE가 서로 다른 ORACLE_HOME을 사용하는 경우도 흔하다.
Q2. EZConnect는 항상 쓸 수 있나요?
sqlnet.ora의 NAMES.DIRECTORY_PATH에 EZCONNECT가 포함돼 있어야 한다. 기본 설정에는 보통 포함돼 있지만, 일부 운영 환경에서는 보안상 EZConnect를 비활성화하기도 한다. tnsping 또는 EZConnect 직접 시도로 확인할 수 있다.
Q3. JDBC URL은 어떻게 작성하나요?
EZConnect 스타일:
jdbc:oracle:thin:@//host:1521/service별칭 스타일:
jdbc:oracle:thin:@(DESCRIPTION=...)또는 tnsnames.ora의 별칭과 함께
oracle.net.tns_admin 시스템 프로퍼티를 설정한다.Q4. tnsnames.ora를 안전하게 편집하는 방법은?
편집 전 백업(`tnsnames.ora.bak`)을 만들고, UTF-8 인코딩 + BOM 없음으로 저장한다. 메모장보다는 Notepad++, VSCode, vim 같은 인코딩 제어 가능 에디터를 권장한다. 저장 후 즉시 `tnsping`으로 검증한다.
Q5. 클라우드 환경(ATP·ADW)에서는 다른가요?
Autonomous Database는 mTLS 또는 TLS 연결을 사용하며, 클라이언트 자격증명 zip 파일(wallet) 안에 tnsnames.ora·sqlnet.ora가 함께 포함돼 있다. zip을 풀고 그 경로를 TNS_ADMIN으로 설정하면 동일한 방식으로 동작한다. ORA-12154는 동일하게 발생할 수 있으며 진단 흐름도 같다.
8. 예방 체크리스트와 결론
ORA-12154는 클라이언트 환경의 일관성 관리와 진단 도구 숙지로 거의 차단할 수 있다. 다음 항목을 점검한다.
- ✓TNS_ADMIN을 명시적으로 설정하고 모든 클라이언트 도구가 같은 값을 보도록 통일
- ✓tnsnames.ora는 한 마스터 파일을 형상 관리 후 자동 배포
- ✓UTF-8 (BOM 없음) 인코딩 표준화, 메모장 저장 회피
- ✓sqlnet.ora의 NAMES.DIRECTORY_PATH에 TNSNAMES·EZCONNECT 항상 포함
- ✓NAMES.DEFAULT_DOMAIN은 비워두거나 명시적으로 관리
- ✓여러 ORACLE_HOME 설치 시 한 홈만 PATH 우선순위로 명시
- ✓새 별칭 추가 시 즉시 tnsping으로 검증, sqlplus로 실제 연결까지 확인
- ✓운영 매뉴얼에 EZConnect 우회 명령 포함 (긴급 진단용)
ORA-12154는 Oracle 네트워크 스택에서 가장 빠르게 실패하는 에러다. 네트워크 통신 전, 클라이언트 메모리 안에서 끝난다. 따라서 해결도 클라이언트 측의 작은 설정 한두 개로 끝나는 경우가 대부분이다. 한 줄로 요약하면 ━ TNS_ADMIN이 어디를 가리키는지 먼저 확인하라. 그 디렉토리의 tnsnames.ora 한 줄이 정답이거나, 그 한 줄을 EZConnect로 우회하면 끝난다.
#ORA12154 #TNS #오라클에러 #tnsnames #TNSADMIN #EZConnect #sqlnetora #NAMESDIRECTORYPATH #tnsping #ORA12541 #ORA12514 #ORA12545 #ORA12170 #네트워크설정 #클라이언트연결
댓글