[ORACLE] ORA-12154 오류 해결 : TNS 설정부터 실전 점검까지

[ORACLE] ORA-12154

 

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

ORACLE을 사용하는 개발자 및 DBA라면 한 번쯤은 반드시 마주치는 오류 중 하나가 바로 ORA-12154입니다. 단순한 설정 문제처럼 보이지만, 실제로는 복합적인 네트워크 구성 요소가 얽혀 있어 원인 분석에 시간이 소요되는 경우가 많습니다. 본 글에서는 이 오류의 발생 원인을 구조적으로 파악하고, 실무 중심의 해결 방법을 제시하며, 잘못된 사례까지 함께 분석합니다.

1. ORA-12154 오류란?

이 오류는 Oracle 클라이언트가 접속하려는 TNS 이름을 해석할 수 없을 때 발생합니다. 즉, SQL*Net 또는 Oracle Net Services가 제공하는 네트워크 주소 정보(TNS entry)를 제대로 찾지 못할 경우 발생합니다.

주로 다음과 같은 명령어 실행 시 나타납니다:

sqlplus user/password@DB_ALIAS

이때 DB_ALIAS가 Oracle 클라이언트가 사용하는 tnsnames.ora 파일에 없거나, 구문 오류가 있거나, 환경변수가 올바르게 설정되지 않았을 경우 ORA-12154 오류가 발생합니다.

2. 주요 원인 및 세부 설명

원인	설명	해결 방향
tnsnames.ora 누락	클라이언트에 해당 alias가 등록되지 않음	tnsnames.ora 파일 확인 및 alias 추가
TNS_ADMIN 경로 미설정	Oracle이 올바른 설정 파일 위치를 찾지 못함	TNS_ADMIN 환경변수 또는 레지스트리 경로 지정
구문 오류	tnsnames.ora 내부 괄호, 쉼표 오류	파일 형식 확인 (Notepad++ 등으로)
대소문자 또는 공백 오류	Alias 오타 또는 복사/붙여넣기 시 공백 포함	명령어와 alias 이름 정확히 일치해야 함
복수 Oracle 클라이언트 설치	다른 버전이 우선 적용되며 충돌 발생	PATH 및 레지스트리 순서 확인

3. 실전에서 겪은 문제 사례

사례: 이중 Oracle 클라이언트 설치

한 제조업체의 Windows 기반 ERP 서버에 Oracle 12c와 19c 클라이언트가 동시에 설치되어 있었습니다. PATH 우선순위에 따라 19c 클라이언트가 먼저 참조되었고, 해당 경로의 tnsnames.ora에는 접속하려는 DB alias가 존재하지 않아 ORA-12154 오류가 발생했습니다.

이 문제는 다음과 같이 해결했습니다:

1. PATH 순서 조정: 12c 클라이언트 경로를 우선순위로 변경
2. TNS_ADMIN 환경 변수 지정: 명시적으로 원하는 tnsnames.ora 경로 지정

4. tnsnames.ora 예시

ORCL =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCP)(HOST = 192.168.10.10)(PORT = 1521))
    (CONNECT_DATA =
      (SERVER = DEDICATED)
      (SERVICE_NAME = orcl)
    )
  )

위 alias인 ORCL을 사용하려면 다음 명령으로 접속 가능합니다:

sqlplus scott/tiger@ORCL

5. 실무 팁: 점검 체크리스트

• tnsnames.ora 파일 위치: Oracle 홈 경로 또는 TNS_ADMIN이 지정하는 위치
• 환경 변수: TNS_ADMIN, ORACLE_HOME, PATH
• 명령행 접속 테스트: tnsping 명령어로 alias 응답 확인
• 문법 확인: 괄호 쌍, 쉼표 위치, 인코딩 문제(UTF-8 vs ANSI)

6. 오류 해결 요약표

오류 원인	점검 항목	해결 방법
tnsnames.ora 없음	파일 존재 여부, alias 등록	alias 추가 또는 파일 생성
환경 변수 문제	TNS_ADMIN, PATH 확인	명확한 경로 지정
다중 클라이언트 설치	우선순위 확인	불필요한 버전 제거 또는 우선순위 조정
문법 오류	괄호, 쉼표, 줄바꿈	문법 자동 포매터 활용

7. 유용한 진단 도구

• tnsping <alias> : 네트워크 설정 확인 및 통신 여부 테스트
• lsnrctl status : 리스너 상태 확인
• SQL Developer 접속 테스트 기능

8. 고급 설정: LDAP, EZCONNECT

기업 환경에서는 tnsnames.ora 대신 LDAP 또는 EZCONNECT 방식도 자주 사용됩니다. 이 경우에도 환경 변수와 alias 인식 문제가 발생할 수 있으므로 관리적 일관성이 매우 중요합니다.

sqlplus scott/tiger@192.168.10.10:1521/orcl

위와 같이 EZCONNECT를 사용할 경우, TNS 파일이 필요 없지만 클라이언트가 해당 구문을 인식할 수 있도록 패치 및 버전 일치가 필요합니다.

9. 마무리: 문제는 대부분 설정에서 시작된다

ORA-12154 오류는 Oracle 서버의 문제가 아니라 클라이언트 설정 오류가 대부분의 원인입니다. 정확한 설정과 환경 변수의 이해만 있다면 해결은 어렵지 않습니다. 실무에서는 일관된 설정관리 정책, tnsnames.ora 형상관리, 클라이언트 버전 통일 등이 장기적인 품질 확보의 핵심입니다.

출처

• Oracle® Net Services Administrator’s Guide 19c
• Oracle 기술지원 문서 Doc ID 125045.1