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

ORA-12227
2026년 09월 10일 | DBMS Error 가이드

이 글에서 다루는 내용

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

ORA-12227 TNS: syntax error 는?

ORA-12227 에러는 Oracle Net Services(TNS)의 설정 파일에서 구문 오류(Syntax Error)가 발생했을 때 나타나는 에러입니다. 주로 tnsnames.ora, sqlnet.ora, listener.ora와 같은 네트워크 설정 파일에 잘못된 구문이 포함되어 있을 때 발생하며, 클라이언트가 Oracle 데이터베이스 서버에 연결을 시도하는 순간 이 에러를 만나게 됩니다. 이 에러는 데이터베이스 자체의 문제가 아니라 네트워크 구성 파일의 문법적인 오류에 의해 발생하므로, 파일 내용을 꼼꼼히 점검하는 것이 해결의 핵심입니다.

주요 발생 원인

1. tnsnames.ora 파일의 괄호 불일치 또는 구문 오류

가장 흔한 원인으로, tnsnames.ora 파일에서 여는 괄호 (와 닫는 괄호 )의 개수가 맞지 않거나, 키워드 오타, 등호(=) 누락 등 다양한 구문 오류가 발생할 수 있습니다. 수작업으로 파일을 편집할 때 특히 자주 발생하며, 파일이 길어질수록 오류를 찾기 어려워집니다. Oracle의 TNS 파서는 매우 엄격하기 때문에 단 하나의 괄호 누락만으로도 전체 연결이 실패할 수 있습니다.

2. sqlnet.ora 파일의 잘못된 파라미터 설정

sqlnet.ora 파일에 지원되지 않는 파라미터 이름을 입력하거나, 값의 형식이 잘못되었을 때 ORA-12227이 발생할 수 있습니다. 예를 들어, SQLNET.AUTHENTICATION_SERVICES 파라미터에 허용되지 않는 값을 설정하거나, 파일 인코딩이 맞지 않는 경우에도 이 에러가 트리거됩니다. 보안 강화를 위해 파일을 수정한 이후 검증 과정 없이 반영할 경우 이 문제가 자주 나타납니다.

3. listener.ora 파일의 리스너 설정 오류

listener.ora 파일 내 SID_LIST_LISTENER 또는 LISTENER 블록의 구조가 올바르지 않은 경우에도 이 에러가 발생합니다. 특히 여러 리스너를 설정하거나 복잡한 서비스 매핑을 구성할 때, 블록 구조의 중첩이 어긋나면 TNS 파서가 구문 오류로 처리합니다. 신규 서비스를 추가하거나 포트를 변경한 뒤 리스너를 재시작할 때 이 에러와 마주치는 경우가 많습니다.

해결 방법

1. tnsnames.ora 파일 점검 및 수정

먼저 tnsnames.ora 파일의 경로를 확인하고, 파일을 열어 괄호 구조와 키워드를 검토합니다.

올바른 tnsnames.ora 예시:

-- tnsnames.ora 올바른 구문 예시
ORCL =
  (DESCRIPTION =
    (ADDRESS_LIST =
      (ADDRESS =
        (PROTOCOL = TCP)
        (HOST = mydbserver.example.com)
        (PORT = 1521)
      )
    )
    (CONNECT_DATA =
      (SERVICE_NAME = orcl.example.com)
    )
  )

잘못된 tnsnames.ora 예시 (괄호 누락):

-- 잘못된 예시: 닫는 괄호 누락으로 ORA-12227 발생
ORCL =
  (DESCRIPTION =
    (ADDRESS_LIST =
      (ADDRESS =
        (PROTOCOL = TCP)
        (HOST = mydbserver.example.com)
        (PORT = 1521)
      )
    -- CONNECT_DATA 블록의 닫는 괄호 누락
    (CONNECT_DATA =
      (SERVICE_NAME = orcl.example.com)
    )
  )

TNS 설정 파일을 수정한 뒤에는 아래 명령어로 파일의 유효성을 반드시 검증하십시오:

-- OS 명령어로 TNS 핑 테스트 (SQL*Plus 세션 전 확인)
-- 터미널/커맨드 프롬프트에서 실행
-- tnsping [TNS 별명]
-- 예시:
-- tnsping ORCL

-- SQL*Plus에서 직접 연결 테스트
-- sqlplus system/password@ORCL

-- 환경변수 확인 쿼리 (DB 접속 후)
SELECT NAME, VALUE
FROM V$PARAMETER
WHERE NAME IN ('service_names', 'db_name', 'instance_name');

2. sqlnet.ora 파일 점검 및 수정

sqlnet.ora의 올바른 파라미터 설정을 확인하고 수정합니다.

-- sqlnet.ora 올바른 설정 예시
-- SQLNET.AUTHENTICATION_SERVICES= (NTS)   -- Windows 환경
-- SQLNET.AUTHENTICATION_SERVICES= (NONE)  -- 일반 환경

-- 아래 SQL로 현재 인증 방식 확인 가능 (DB 접속 후)
SELECT USERNAME, AUTHENTICATION_TYPE
FROM DBA_USERS
WHERE ACCOUNT_STATUS = 'OPEN'
ORDER BY USERNAME;

-- 네트워크 파라미터 확인
SELECT NAME, VALUE
FROM V$PARAMETER
WHERE NAME LIKE '%remote%'
   OR NAME LIKE '%sqlnet%'
ORDER BY NAME;

3. listener.ora 파일 점검 및 리스너 재시작

-- listener.ora 올바른 구문 예시
/*
LISTENER =
  (DESCRIPTION_LIST =
    (DESCRIPTION =
      (ADDRESS = (PROTOCOL = TCP)(HOST = mydbserver)(PORT = 1521))
    )
  )

SID_LIST_LISTENER =
  (SID_LIST =
    (SID_DESC =
      (GLOBAL_DBNAME = orcl.example.com)
      (ORACLE_HOME = /u01/app/oracle/product/19.0.0/dbhome_1)
      (SID_NAME = ORCL)
    )
  )
*/

-- 리스너 상태 확인 및 서비스 목록 조회 (DB 접속 후)
SELECT INST_ID,
       INSTANCE_NAME,
       HOST_NAME,
       STATUS
FROM GV$INSTANCE;

-- 등록된 서비스 확인
SELECT NAME, NETWORK_NAME, CREATION_DATE
FROM DBA_SERVICES
ORDER BY NAME;

리스너 관련 OS 명령어로 상태를 점검하고 재시작합니다:

-- 아래는 OS 레벨 커맨드입니다 (주석으로 표기)
-- lsnrctl status          → 리스너 상태 확인
-- lsnrctl stop            → 리스너 중지
-- lsnrctl start           → 리스너 시작
-- lsnrctl reload          → 설정 파일 재로드 (재시작 없이)

-- 리스너 로그 확인을 위한 경로 조회
SELECT VALUE
FROM V$DIAG_INFO
WHERE NAME = 'Diag Trace';

예방 방법

1. 설정 파일 변경 전 반드시 백업 및 버전 관리 적용

tnsnames.ora, sqlnet.ora, listener.ora 등 TNS 관련 파일은 수정 전 항상 타임스탬프가 포함된 이름으로 백업 파일을 생성하는 습관을 들이십시오. 가능하다면 Git과 같은 버전 관리 시스템에 설정 파일을 포함하여 변경 이력을 추적하고, 롤백이 필요한 상황에서 즉시 이전 버전으로 복구할 수 있도록 준비해야 합니다. 실무에서는 변경 이력 없이 수작업으로 파일을 수정하다가 문제가 발생한 경우, 원인 파악에 상당한 시간이 소요되는 경우가 많습니다.

2. Oracle Net Manager 또는 Oracle Net Configuration Assistant(NETCA) 활용

수작업으로 설정 파일을 직접 편집하는 것보다 Oracle이 공식 제공하는 GUI 도구인 Oracle Net Manager나 NETCA를 활용하면 구문 오류 발생 가능성을 크게 줄일 수 있습니다. 이 도구들은 내부적으로 구문 검증을 수행하므로, 잘못된 구문이 파일에 저장되는 것을 사전에 방지해 줍니다. 대규모 환경에서는 Oracle Enterprise Manager(OEM)의 네트워크 관리 기능을 함께 활용하면 중앙 집중식으로 설정을 관리하고 모니터링할 수 있어 운영 효율성이 높아집니다.