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

ORA-12162
2026년 09월 08일 | DBMS Error 가이드

이 글에서 다루는 내용

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

ORA-12162 TNS: net service name is incorrectly specified 는?

ORA-12162 에러는 Oracle Net Services(TNS)에서 네트워크 서비스 이름이 올바르게 지정되지 않았을 때 발생하는 연결 오류입니다. 주로 클라이언트가 데이터베이스에 연결을 시도할 때 tnsnames.ora 파일이나 환경 변수에서 서비스 이름을 찾지 못하거나 잘못 구성된 경우에 나타납니다. 이 에러는 개발 환경, 운영 환경을 가리지 않고 자주 발생하며, DBA나 개발자 모두에게 친숙한 오류 중 하나입니다.

주요 발생 원인

1. ORACLE_SID 또는 TWO_TASK 환경 변수 미설정 혹은 잘못된 값

Oracle 클라이언트는 연결 대상 데이터베이스를 식별하기 위해 ORACLE_SID 환경 변수를 참조합니다. 이 환경 변수가 설정되지 않았거나 빈 문자열(“”)로 설정된 경우, TNS는 서비스 이름을 결정할 수 없어 ORA-12162를 발생시킵니다. 특히 Linux/Unix 환경에서 세션이 전환되거나 스크립트 실행 시 환경 변수가 초기화되지 않는 경우에 자주 관찰됩니다. TWO_TASK 환경 변수 역시 마찬가지로 잘못된 서비스 이름을 가리키고 있을 경우 동일한 에러를 유발합니다.

2. tnsnames.ora 파일 내 서비스 이름 오타 또는 구문 오류

tnsnames.ora 파일에서 서비스 이름 항목이 잘못 정의되어 있거나 구문 오류가 포함된 경우 ORA-12162가 발생합니다. 예를 들어 서비스 이름에 특수 문자, 공백, 또는 잘못된 괄호 매핑이 포함되어 있으면 TNS 리졸버가 해당 항목을 올바르게 파싱하지 못합니다. 운영 환경에서 여러 DBA가 파일을 공동 관리하는 경우 실수로 기존 항목이 손상되는 사례도 적지 않습니다.

3. SQLNET.ORA 또는 LDAP 기반 이름 해석 설정 오류

sqlnet.ora 파일의 NAMES.DIRECTORY_PATH 설정이 잘못 구성되면, Oracle 클라이언트가 이름 해석 방법을 찾지 못해 에러가 발생합니다. LDAP(Oracle Internet Directory) 또는 Easy Connect 방식을 사용할 때 해당 설정이 누락되거나 우선순위가 잘못 지정된 경우, 올바른 서비스 이름이 있어도 해석에 실패할 수 있습니다. 대규모 엔터프라이즈 환경에서는 이름 해석 방식이 혼용되는 경우가 많아 원인 파악이 쉽지 않습니다.

해결 방법

원인 1: 환경 변수 확인 및 설정

먼저 현재 환경 변수 상태를 확인합니다.

-- SQL*Plus 접속 전 Linux/Unix 쉘에서 확인
-- $ echo $ORACLE_SID
-- $ echo $TWO_TASK
-- $ echo $ORACLE_HOME

-- 환경 변수 설정 예시 (bash)
-- export ORACLE_SID=ORCL
-- export ORACLE_HOME=/u01/app/oracle/product/19c/dbhome_1
-- export PATH=$ORACLE_HOME/bin:$PATH

-- 환경 변수 설정 후 접속 테스트
-- $ sqlplus sys/password@ORCL as sysdba

-- DB 내부에서 현재 인스턴스 이름 확인
SELECT INSTANCE_NAME, STATUS, DB_UNIQUE_NAME
FROM   V$INSTANCE;

-- 잘못된 접속 예 (서비스 이름 누락)
-- sqlplus scott/tiger@   <-- 이렇게 하면 ORA-12162 발생

-- 올바른 접속 예
-- sqlplus scott/tiger@ORCL
-- sqlplus scott/tiger@//hostname:1521/ORCL  (Easy Connect 방식)

원인 2: tnsnames.ora 파일 점검 및 수정

tnsnames.ora 파일의 올바른 구문 예시와 검증 방법을 확인합니다.

-- tnsnames.ora 올바른 구문 예시
-- ORCL =
--   (DESCRIPTION =
--     (ADDRESS = (PROTOCOL = TCP)(HOST = dbserver01)(PORT = 1521))
--     (CONNECT_DATA =
--       (SERVER = DEDICATED)
--       (SERVICE_NAME = ORCL)
--     )
--   )

-- tnsnames.ora 파일 위치 확인 (SQL*Plus에서)
SELECT VALUE
FROM   V$PARAMETER
WHERE  NAME = 'tns_admin';

-- tnsping 명령어로 TNS 연결 가능 여부 확인 (OS 쉘에서 실행)
-- $ tnsping ORCL

-- 결과 예시 (성공):
-- Used TNSNAMES adapter to resolve the alias
-- Attempting to contact (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=dbserver01)(PORT=1521))...)
-- OK (10 msec)

-- 등록된 서비스 목록 확인 (리스너가 실행 중인 서버에서)
-- $ lsnrctl services

-- 리스너 상태 확인
-- $ lsnrctl status

-- DB에서 서비스 이름 확인
SELECT NAME, NETWORK_NAME, PDB
FROM   V$SERVICES
ORDER BY NAME;

원인 3: sqlnet.ora 이름 해석 설정 수정

-- sqlnet.ora 올바른 NAMES.DIRECTORY_PATH 설정 예시
-- NAMES.DIRECTORY_PATH = (TNSNAMES, EZCONNECT)
-- 또는 LDAP 포함 시:
-- NAMES.DIRECTORY_PATH = (LDAP, TNSNAMES, EZCONNECT)

-- Easy Connect 방식으로 직접 연결 테스트 (tnsnames.ora 우회)
-- $ sqlplus scott/tiger@//192.168.1.100:1521/ORCL

-- 현재 적용된 Oracle Net 파라미터 확인
SELECT *
FROM   V$PARAMETER
WHERE  NAME LIKE '%listener%'
    OR NAME LIKE '%service%'
ORDER BY NAME;

-- TNS_ADMIN 환경 변수로 설정 파일 경로를 명시적으로 지정하는 방법
-- export TNS_ADMIN=/u01/app/oracle/network/admin

-- 설정 파일 경로 일관성 점검 쿼리
SELECT NAME, VALUE
FROM   V$PARAMETER
WHERE  NAME IN ('db_name', 'db_unique_name', 'service_names', 'instance_name');

예방 방법

1. 표준화된 환경 변수 프로파일 관리

모든 Oracle 관련 환경 변수(ORACLE_SID, ORACLE_HOME, TNS_ADMIN 등)를 중앙화된 프로파일 스크립트(예: /etc/profile.d/oracle.sh 또는 사용자별 .bash_profile)에 명시적으로 정의하고 버전 관리 시스템(Git 등)으로 이력을 관리하는 것이 좋습니다. 신규 서버 구축 시 해당 스크립트를 자동으로 배포하는 Ansible, Chef 같은 구성 관리 도구를 활용하면 설정 누락으로 인한 에러를 원천 차단할 수 있습니다.

2. tnsnames.ora 변경 시 반드시 tnsping 검증 절차 수행

tnsnames.ora 파일을 수정한 후에는 반드시 tnsping [서비스명] 명령어로 연결 가능 여부를 검증하고, 변경 내역을 별도 문서 또는 형상 관리 시스템에 기록해야 합니다. 특히 운영 환경에서는 변경 전 원본 파일을 백업(tnsnames.ora.YYYYMMDD 형식)하고, 변경 후 최소 2명 이상의 DBA가 크로스 체크하는 이중 검증 체계를 운영하면 구문 오류로 인한 장애를 예방할 수 있습니다.