[오라클 에러] ORA-12154 TNS:could not resolve the connect identifier - 5가지 원인과 해결방법 (접속 에러 3종 비교)
테스트 환경: Oracle Client 11g / 12c / 19c / 21c, Oracle Linux 8 / Windows 11
ORA-12154는 오라클 클라이언트가 가장 먼저 마주칠 수 있는 접속 에러입니다. ORA-12541(리스너 없음)이나 ORA-12514(서비스 모름)이 "서버에 도달했는데 안 됨"이라면, ORA-12154는 "서버에 도달조차 못함" 의 의미입니다.
이 글로 본 블로그의 접속 에러 3종 시리즈가 완성됩니다.
- ORA-12154: 별칭(connect identifier) 자체를 못 풀어서 어디로 가야 할지 모름
- ORA-12541: 어디로 가야 할지는 알았는데 그 호스트의 리스너가 죽음
- ORA-12514: 리스너는 살아있는데 요청한 서비스를 모름
이번 글에서는 ORA-12154의 5가지 원인을 분류하고, 특히 여러 오라클 클라이언트가 설치된 환경에서 자주 발생하는 환경변수 충돌까지 정리했습니다. 급하신 분은 빠른 진단 체크리스트부터 보세요.
에러 메시지 전문
ORA-12154: TNS:could not resolve the connect identifier specified
ORA-12154: TNS: 지정된 접속 식별자를 해석할 수 없습니다.
일부 버전에서는 다음 형태로도 보일 수 있습니다.
ORA-12154: TNS:could not resolve service name
다만 실제 동작은 동일합니다.
★ 접속 에러 3종 비교 (12154 vs 12541 vs 12514)
세 에러가 발생하는 단계를 그림으로 표현하면 다음과 같습니다.
클라이언트가 SQL 실행
│
├─ 1단계: 별칭(예: PRODDB)을 풀어서 host:port를 찾기
│ └─ 실패 시 → ORA-12154
│
├─ 2단계: host:port의 리스너에 접속
│ └─ 실패 시 → ORA-12541
│
├─ 3단계: 리스너에 service_name 요청
│ └─ 실패 시 → ORA-12514
│
└─ 4단계: DB 인스턴스 접속 → 인증(ORA-01017 등)
항목 ORA-12154 ORA-12541 ORA-12514
| 단계 | 1단계 (이름 해석) | 2단계 (리스너 접속) | 3단계 (서비스 매칭) |
| 의미 | 별칭 못 풂 | 리스너 응답 없음 | 서비스 미등록 |
| 위치 | 클라이언트 측 문제 | 서버 또는 네트워크 | 서버 측 문제 |
| 핵심 점검 파일 | tnsnames.ora, sqlnet.ora | listener.ora | service_names |
| 클라이언트 환경변수 영향 | ⭐⭐⭐⭐⭐ | - | - |
가장 중요한 차이: ORA-12154는 클라이언트 PC의 설정 문제입니다. 서버는 멀쩡합니다.
한 줄 진단법: 같은 별칭을 다른 PC나 다른 서버에서는 잘 쓰는데 내 PC에서만 안 되면 거의 100% ORA-12154 케이스입니다.
ORA-12154의 본질 - "별칭 해석"의 의미
ORA-12154를 이해하려면 클라이언트가 별칭(connect identifier)을 어떻게 해석하는지 알아야 합니다.
사용자 입력 → 실제 접속 정보 변환
# 사용자가 입력한 것
sqlplus scott/tiger@PRODDB
# 클라이언트가 PRODDB라는 별칭을 해석해서 알아내야 하는 것
# 1. 어떤 호스트에 접속? → 192.168.10.5
# 2. 어떤 포트? → 1521
# 3. 어떤 서비스? → orclpdb
이 해석 과정에서 클라이언트가 사용하는 정보 출처(naming method)는 sqlnet.ora의 NAMES.DIRECTORY_PATH 파라미터로 결정됩니다.
NAMES.DIRECTORY_PATH 기본값
NAMES.DIRECTORY_PATH = (TNSNAMES, EZCONNECT)
값 의미
| TNSNAMES | tnsnames.ora 파일 사용 (가장 일반적) |
| EZCONNECT | host:port/service_name 형식 직접 입력 |
| LDAP | LDAP 디렉토리 서버 사용 |
| HOSTNAME | DNS 호스트명 자동 매칭 (deprecated) |
ORA-12154는 이 모든 방법으로도 별칭을 못 풀었다는 의미입니다.
빠른 진단 체크리스트
ORA-12154가 발생했을 때 30초 만에 원인을 좁히는 순서입니다.
- tnsnames.ora 파일이 어디 있는지 확인 → 파일 위치 자체가 문제일 수 있음
- 파일 안에 해당 별칭이 정확히 있는지 확인 → 오타 / 누락
- 파일 구문 오류 확인 → 괄호 짝, 들여쓰기
- TNS_ADMIN 환경변수 확인 → 클라이언트가 어느 파일을 보는지
- 여러 ORACLE_HOME 설치 환경인지 확인 → 어느 것을 쓰는지
원인 1: tnsnames.ora 파일에 별칭이 없거나 오타 (가장 흔함)
ORA-12154의 50% 이상이 이 케이스입니다.
진단 방법
1단계: tnsnames.ora 위치 찾기
# Linux/Unix
find / -name tnsnames.ora 2>/dev/null
echo $ORACLE_HOME
echo $TNS_ADMIN
# 일반적 위치
# $ORACLE_HOME/network/admin/tnsnames.ora
# $TNS_ADMIN/tnsnames.ora
:: Windows
where tnsnames.ora
echo %ORACLE_HOME%
echo %TNS_ADMIN%
:: 일반적 위치
:: %ORACLE_HOME%\network\admin\tnsnames.ora
:: %TNS_ADMIN%\tnsnames.ora
2단계: 파일 안에 별칭이 있는지 확인
# Linux에서 PRODDB 별칭 찾기
grep -i "^PRODDB" $TNS_ADMIN/tnsnames.ora
원하는 별칭이 안 나오면 파일에 추가되지 않은 것입니다.
해결 방법
tnsnames.ora 파일에 별칭을 추가합니다.
PRODDB =
(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = 192.168.10.5)(PORT = 1521))
(CONNECT_DATA =
(SERVER = DEDICATED)
(SERVICE_NAME = orclpdb)
)
)
실무 팁
운영 환경에서는 tnsnames.ora를 중앙에서 관리하고 모든 클라이언트에 동일 파일을 배포하는 것이 표준입니다. 사용자별로 다르게 설정하면 ORA-12154 사고가 끊임없이 발생합니다.
원인 2: tnsnames.ora 구문 오류 (괄호 짝, 오타)
파일이 있고 별칭도 있는데 ORA-12154가 발생한다면 파일 어딘가에 구문 오류가 있을 가능성이 높습니다.
흔한 구문 오류
PRODDB =
(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = 192.168.10.5)(PORT = 1521))
(CONNECT_DATA =
(SERVICE_NAME = orclpdb)
)
)
←── 여기에 짝이 안 맞는 괄호 1개 더
TESTDB = ← 위 문제 때문에 이 별칭부터 모두 인식 안 됨
(DESCRIPTION = ...
중요한 점: 파일 안 한 곳의 구문 오류가 그 이후의 모든 별칭을 인식 불가로 만들 수 있습니다.
진단 방법
1) tnsping으로 별칭 동작 확인
tnsping PRODDB
별칭이 정상이면 응답이 옵니다.
OK (10 msec)
별칭이 인식 안 되면:
TNS-03505: Failed to resolve name
2) 별칭별로 차례대로 tnsping
tnsping PRODDB
tnsping TESTDB
tnsping DEVDB
어느 별칭부터 실패하는지 찾으면, 그 직전 별칭 정의에 구문 오류가 있다는 뜻입니다.
해결 방법
자주 발생하는 구문 오류 패턴:
❌ 괄호 짝 안 맞음
(ADDRESS = (PROTOCOL = TCP)(HOST = 192.168.10.5)(PORT = 1521)
❌ 들여쓰기 잘못으로 별칭과 본문 연결 안 됨
PRODDB =
(DESCRIPTION = ... ← 최상위로 가버림
❌ 콤마 사용 (오라클 tnsnames.ora는 콤마 안 씀)
(ADDRESS = (PROTOCOL=TCP), (HOST=192.168.10.5), (PORT=1521))
❌ 따옴표 안 쓰는데 따옴표 들어감
(HOST = "192.168.10.5")
수정 후 클라이언트 도구를 재시작해야 반영됩니다(SQL Developer, Toad 등).
★ 원인 3: TNS_ADMIN 환경변수 누락 또는 잘못 설정
가장 까다로운 케이스 중 하나입니다. 파일도 있고 내용도 맞는데, 클라이언트가 그 파일을 안 보고 있는 경우입니다.
진단 방법
Linux/Unix
# 환경변수 확인
echo $TNS_ADMIN
echo $ORACLE_HOME
# 실제로 어느 파일을 보는지 추적
strace -f -e openat sqlplus scott/tiger@PRODDB 2>&1 | grep -i tnsnames
Windows
echo %TNS_ADMIN%
echo %ORACLE_HOME%
:: 또는 시스템 환경변수에서 확인
set | findstr ORACLE
클라이언트의 tnsnames.ora 탐색 순서
오라클 클라이언트가 tnsnames.ora를 찾는 순서는 다음과 같습니다.
- TNS_ADMIN 환경변수가 가리키는 경로
- $ORACLE_HOME/network/admin/
- (Windows만) 레지스트리의 TNS_ADMIN 값
- (Linux 옛 환경) /etc/
상위 단계에서 찾으면 하위 단계는 안 봅니다. 그래서 TNS_ADMIN이 잘못된 경로를 가리키면 정상적인 tnsnames.ora가 있어도 무시됩니다.
해결 방법
Linux: 영구 설정
# ~/.bashrc 또는 ~/.bash_profile에 추가
export ORACLE_HOME=/u01/app/oracle/product/19c/client_1
export TNS_ADMIN=$ORACLE_HOME/network/admin
export PATH=$ORACLE_HOME/bin:$PATH
source ~/.bashrc
Windows: 환경변수 GUI 설정
내 PC 우클릭 → 속성 → 고급 시스템 설정 → 환경 변수
시스템 변수에 추가:
- ORACLE_HOME: C:\app\oracle\product\19.0.0\client_1
- TNS_ADMIN: %ORACLE_HOME%\network\admin
실무 팁
운영 환경에서는 TNS_ADMIN을 명시적으로 설정하는 것을 권장합니다. ORACLE_HOME에 의존하지 않으면 클라이언트 업그레이드 시 tnsnames.ora를 재배포할 필요가 없습니다.
★ 원인 4: 여러 ORACLE_HOME 설치 환경의 충돌 (Windows에서 흔함)
이 케이스는 다른 한국어 블로그에서 깊이 다루지 않는 영역입니다.
무엇이 문제인가
한 PC에 SQL Developer, Toad, Instant Client, Forms 등 여러 오라클 클라이언트가 설치되어 있으면 각자 다른 ORACLE_HOME을 가집니다. 사용자는 한 곳의 tnsnames.ora를 수정했는데, 클라이언트는 다른 곳을 보고 있어서 ORA-12154가 발생합니다.
진단 방법
Windows에서 설치된 ORACLE_HOME 목록 확인
:: 레지스트리에서 확인
reg query HKLM\SOFTWARE\Oracle /s | findstr ORACLE_HOME
여러 경로가 나오면 충돌 가능성이 있습니다.
현재 클라이언트가 사용하는 ORACLE_HOME 확인
:: 실제 사용 중인 sqlplus 위치
where sqlplus
:: 그 폴더 상위의 network\admin\tnsnames.ora가 실제 사용 파일
해결 방법
방법 1: TNS_ADMIN을 강제 지정
여러 ORACLE_HOME이 있어도 TNS_ADMIN은 우선됩니다.
:: 시스템 환경변수에 TNS_ADMIN 추가
:: → 모든 클라이언트가 한 곳의 tnsnames.ora 사용
방법 2: 각 ORACLE_HOME의 tnsnames.ora를 동일 내용으로 동기화
:: 표준 파일을 복사
xcopy /Y C:\standard\tnsnames.ora C:\app\oracle_home1\network\admin\
xcopy /Y C:\standard\tnsnames.ora C:\app\oracle_home2\network\admin\
번거롭지만 가장 확실한 방법입니다.
실무 팁
운영자 PC에서 새 클라이언트를 설치할 때마다 ORA-12154가 빈번히 발생합니다. 표준 tnsnames.ora를 git이나 공유 폴더에 두고, 새 클라이언트 설치 시 그 파일을 강제 복사하는 절차를 만들어 두세요.
원인 5: sqlnet.ora의 NAMES.DIRECTORY_PATH 설정
tnsnames.ora는 멀쩡한데도 클라이언트가 LDAP 같은 다른 방법을 시도해서 실패하는 경우입니다.
진단 방법
# sqlnet.ora 확인
cat $TNS_ADMIN/sqlnet.ora
다음과 같이 LDAP만 설정되어 있으면 tnsnames.ora를 보지 않습니다.
NAMES.DIRECTORY_PATH = (LDAP)
해결 방법
sqlnet.ora를 수정해서 TNSNAMES를 포함합니다.
NAMES.DIRECTORY_PATH = (TNSNAMES, EZCONNECT, LDAP)
순서가 중요합니다. 먼저 나열된 방법이 우선 시도됩니다. 일반 환경에서는 TNSNAMES를 가장 앞에 두는 것을 권장합니다.
파일이 없는 경우
sqlnet.ora 파일 자체가 없어도 됩니다. 이 경우 오라클은 기본값 (TNSNAMES, EZCONNECT)을 사용합니다. 이상한 sqlnet.ora가 있어서 문제가 된다면 차라리 그 파일을 백업하고 삭제하는 것이 빠른 해결책입니다.
★ Easy Connect로 우회 (즉시 사용 가능)
ORA-12154의 원인을 분석하는 동안 별칭 없이 직접 접속할 수 있는 방법이 있습니다.
Easy Connect 구문
sqlplus scott/tiger@호스트:포트/서비스명
예시:
sqlplus scott/tiger@192.168.10.5:1521/orclpdb
이 방식은 tnsnames.ora를 사용하지 않기 때문에 ORA-12154가 발생하지 않습니다.
Easy Connect 활용 시나리오
- tnsnames.ora 설정 문제로 급하게 접속해야 할 때
- 새 서버에 임시 접속할 때
- 자동화 스크립트에서 별칭 의존성을 없애고 싶을 때
제한사항
Easy Connect는 sqlnet.ora의 NAMES.DIRECTORY_PATH에 EZCONNECT가 포함되어 있어야 동작합니다. 기본값에는 포함되어 있으니 일반 환경에서는 바로 사용 가능합니다.
빠른 해결 체크리스트 (종합)
5분 안에 원인을 좁히는 종합 체크리스트입니다.
순서 확인 항목 명령어
| 1 | tnsnames.ora 위치 확인 | find / -name tnsnames.ora 또는 where tnsnames.ora |
| 2 | TNS_ADMIN 환경변수 | echo $TNS_ADMIN |
| 3 | 별칭 존재 여부 | grep -i "^별칭" tnsnames.ora |
| 4 | tnsping 동작 | tnsping 별칭 |
| 5 | 임시 우회 시도 | Easy Connect 사용 |
| 6 | sqlnet.ora 설정 | cat $TNS_ADMIN/sqlnet.ora |
이 5단계로 ORA-12154의 95% 이상이 해결됩니다.
그래도 안 풀린다면
위 5가지로도 해결되지 않는 드문 케이스:
- 파일 권한 문제: tnsnames.ora 읽기 권한이 없는 경우 (chmod 644)
- 파일 인코딩 문제: BOM이 포함된 UTF-8 파일에서 발생 가능 (UTF-8 without BOM으로 저장)
- 줄바꿈 문제: Windows에서 만든 파일을 Linux에서 사용 시 (dos2unix tnsnames.ora)
- LDAP 디렉토리 서버 응답 없음: NAMES.DIRECTORY_PATH에 LDAP만 있는 경우
- 윈도우 레지스트리 충돌: 여러 ORACLE_HOME 등록 시
마무리
ORA-12154는 메시지가 다소 추상적이지만, 본질은 "클라이언트가 별칭을 못 풀었다" 는 단순한 문제입니다. 거의 모든 케이스가 클라이언트 PC의 설정에 원인이 있으며, 서버는 멀쩡합니다.
같은 별칭이 다른 PC에서는 잘 되는지 확인하면 가장 빠른 분리 진단이 가능합니다. 잘 된다면 본인 PC의 환경변수, tnsnames.ora 파일 위치, sqlnet.ora 설정을 차례로 점검하세요.
운영 환경에서 ORA-12154 사고를 근본적으로 줄이려면 TNS_ADMIN 표준화가 가장 좋습니다. 한 경로를 정해 두고 모든 클라이언트가 그 파일을 보도록 강제하면 클라이언트 업그레이드, 신규 설치, 마이그레이션 시 발생하는 95%의 사고를 막을 수 있습니다.
이로써 본 블로그의 접속 에러 3종 시리즈(12154, 12541, 12514) 가 완성되었습니다. 세 에러를 단계별로 이해하면 어떤 접속 문제가 발생해도 빠르게 원인을 좁힐 수 있습니다.
비슷한 케이스를 겪으셨거나, 위 방법으로도 해결되지 않은 상황이 있다면 댓글로 공유해 주세요.