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

ORA-24035
2026년 10월 02일 | DBMS Error 가이드

이 글에서 다루는 내용

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

ORA-24035 AQ agent not a subscriber of queue 는?

ORA-24035 에러는 Oracle Advanced Queuing(AQ) 환경에서 특정 AQ 에이전트(Agent)가 해당 큐(Queue)의 구독자(Subscriber)로 등록되어 있지 않은 상태에서 메시지를 수신하거나 dequeue 작업을 시도할 때 발생하는 에러입니다. Oracle AQ는 발행-구독(Publish-Subscribe) 패턴을 기반으로 동작하기 때문에, 에이전트가 큐에서 메시지를 소비하려면 반드시 사전에 구독자로 등록되어 있어야 합니다. 즉, 구독 관계가 설정되지 않은 에이전트가 메시지 수신을 요청할 경우 Oracle 엔진은 이 에러를 반환하며 해당 작업을 거부합니다.

주요 발생 원인

1. 에이전트가 큐의 구독자로 등록되지 않은 경우

가장 흔한 원인으로, AQ 에이전트가 해당 큐(Queue)에 DBMS_AQADM.ADD_SUBSCRIBER 프로시저를 통해 구독자로 추가되지 않은 상태에서 dequeue를 시도할 때 발생합니다. 특히 개발 초기 단계나 환경 이전(Migration) 시 구독자 등록 스크립트가 누락되는 경우가 빈번하므로 주의가 필요합니다.

2. 에이전트 이름 또는 주소(Address) 불일치

구독자로 등록할 때 사용한 에이전트 이름(agent name)과 실제 dequeue 요청 시 사용하는 에이전트 이름이 대소문자(case sensitivity)나 스펠링 차이로 인해 일치하지 않을 때 발생합니다. Oracle AQ는 에이전트 이름을 정확히 일치시켜 구독 여부를 판단하므로, 단 한 글자의 차이도 에러로 이어질 수 있습니다.

3. 큐 재생성 또는 구독자 정보 손실

큐를 DROP 후 재생성하거나, 데이터베이스 복원(Restore) 또는 임포트(Import) 작업 이후 구독자 정보가 초기화되어 기존에 등록된 구독자 정보가 사라지는 경우에도 이 에러가 발생합니다. 이런 상황은 운영 환경에서 발생할 경우 서비스 장애로 이어질 수 있으므로, 인프라 작업 후 반드시 구독자 목록을 검증해야 합니다.

해결 방법

원인 1 해결: 에이전트를 구독자로 등록

현재 큐에 등록된 구독자 목록을 먼저 확인하고, 누락된 에이전트를 구독자로 추가합니다.

-- 현재 큐의 구독자 목록 확인
SELECT queue_name, name, address, protocol
FROM dba_queue_subscribers
WHERE queue_name = 'YOUR_QUEUE_NAME';

-- 에이전트 객체 생성 후 구독자 등록
DECLARE
  v_agent SYS.AQ$_AGENT;
BEGIN
  -- 에이전트 정의: 이름, 주소(큐), 프로토콜
  v_agent := SYS.AQ$_AGENT(
    'MY_AGENT',          -- 에이전트 이름
    'MY_SCHEMA.MY_QUEUE', -- 큐 주소 (schema.queue_name)
    0                    -- 프로토콜 (0 = Oracle AQ 내부)
  );

  -- 구독자 추가
  DBMS_AQADM.ADD_SUBSCRIBER(
    queue_name => 'MY_SCHEMA.MY_QUEUE',
    subscriber => v_agent,
    rule       => NULL  -- 특정 조건 없이 모든 메시지 수신
  );

  COMMIT;
  DBMS_OUTPUT.PUT_LINE('구독자 등록 완료: MY_AGENT');
END;
/

원인 2 해결: 에이전트 이름 불일치 수정

등록된 구독자 이름과 dequeue 시 사용하는 에이전트 이름이 정확히 일치하는지 확인합니다.

-- 등록된 구독자 이름 정확히 확인
SELECT name, address, queue_name
FROM dba_queue_subscribers
WHERE queue_name = 'MY_QUEUE';

-- Dequeue 시 에이전트 이름을 등록된 이름과 동일하게 설정
DECLARE
  v_dequeue_options   DBMS_AQ.DEQUEUE_OPTIONS_T;
  v_message_props     DBMS_AQ.MESSAGE_PROPERTIES_T;
  v_payload           VARCHAR2(4000);
  v_msgid             RAW(16);
BEGIN
  -- 반드시 등록된 에이전트 이름과 동일하게 설정 (대소문자 주의)
  v_dequeue_options.consumer_name := 'MY_AGENT'; -- DBA_QUEUE_SUBSCRIBERS.NAME 값과 동일해야 함
  v_dequeue_options.navigation    := DBMS_AQ.FIRST_MESSAGE;
  v_dequeue_options.wait          := DBMS_AQ.NO_WAIT;

  DBMS_AQ.DEQUEUE(
    queue_name         => 'MY_SCHEMA.MY_QUEUE',
    dequeue_options    => v_dequeue_options,
    message_properties => v_message_props,
    payload            => v_payload,
    msgid              => v_msgid
  );

  COMMIT;
  DBMS_OUTPUT.PUT_LINE('수신된 메시지: ' || v_payload);
END;
/

원인 3 해결: 큐 재생성 후 구독자 재등록

큐를 재생성한 경우 구독자를 일괄 재등록하는 스크립트를 실행합니다.

-- 1단계: 기존 구독자 목록 백업 (재생성 전에 미리 수행)
CREATE TABLE aq_subscriber_backup AS
SELECT queue_name, name, address, protocol, transformation
FROM dba_queue_subscribers
WHERE queue_name IN ('MY_SCHEMA.MY_QUEUE');

-- 2단계: 큐 재생성 후 구독자 일괄 재등록 프로시저
DECLARE
  v_agent SYS.AQ$_AGENT;
BEGIN
  FOR rec IN (SELECT name, address FROM aq_subscriber_backup
              WHERE queue_name = 'MY_SCHEMA.MY_QUEUE') LOOP

    v_agent := SYS.AQ$_AGENT(rec.name, rec.address, 0);

    BEGIN
      DBMS_AQADM.ADD_SUBSCRIBER(
        queue_name => 'MY_SCHEMA.MY_QUEUE',
        subscriber => v_agent
      );
      DBMS_OUTPUT.PUT_LINE('재등록 성공: ' || rec.name);
    EXCEPTION
      WHEN OTHERS THEN
        DBMS_OUTPUT.PUT_LINE('재등록 실패: ' || rec.name || ' - ' || SQLERRM);
    END;
  END LOOP;
  COMMIT;
END;
/

예방 방법

1. 구독자 등록 상태 정기 모니터링 자동화

운영 환경에서는 애플리케이션 기동 전 또는 정기 배치 작업에서 AQ 구독자 등록 상태를 자동으로 검증하는 스크립트를 포함시켜야 합니다. DBA_QUEUE_SUBSCRIBERS 뷰를 조회하여 필수 구독자가 누락된 경우 알림을 발생시키는 모니터링 Job을 DBMS_SCHEDULER로 등록해두면, 인프라 작업 이후 발생할 수 있는 구독자 손실을 조기에 감지할 수 있습니다.

2. AQ 구독자 등록 스크립트를 변경 관리(형상 관리) 체계에 포함

큐 생성 및 구독자 등록 스크립트를 Git 등의 형상 관리 도구에 반드시 포함시키고, 데이터베이스 배포 파이프라인(CI/CD)에서 자동으로 실행되도록 구성해야 합니다. 환경 이전이나 DR(Disaster Recovery) 전환 시에도 해당 스크립트가 자동으로 적용되어 구독자 누락으로 인한 장애를 원천 차단할 수 있습니다.