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

작성자:

ORA-02211
2026년 08월 12일 | DBMS Error 가이드

이 글에서 다루는 내용

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

ORA-02211 invalid value for PCTFREE or PCTUSED 는?

ORA-02211 에러는 Oracle 데이터베이스에서 테이블이나 인덱스를 생성하거나 변경할 때 PCTFREE 또는 PCTUSED 파라미터에 유효하지 않은 값을 지정했을 때 발생하는 에러입니다. PCTFREE는 블록 내에서 업데이트를 위해 예약해 두는 공간의 비율(0~99)을 의미하고, PCTUSED는 블록이 다시 삽입 대상이 되기 위한 최소 사용 비율(1~99)을 나타냅니다. 두 값의 합이 100을 초과하거나, 허용 범위를 벗어난 음수 또는 100 이상의 값을 입력하면 이 에러가 발생합니다.

주요 발생 원인

1. PCTFREE 또는 PCTUSED에 허용 범위를 벗어난 값 지정

PCTFREE의 유효 범위는 0에서 99 사이이며, PCTUSED의 유효 범위는 1에서 99 사이입니다. 음수 값이나 100 이상의 값(예: -1, 100, 150 등)을 지정하면 Oracle은 즉시 ORA-02211 에러를 반환합니다. 실무에서는 스크립트 자동화 과정에서 변수 치환이 잘못되어 이상한 값이 들어오는 경우가 종종 발생합니다.

2. PCTFREE + PCTUSED의 합이 100을 초과하는 경우

Oracle은 PCTFREE와 PCTUSED의 합이 100을 초과하지 않아야 한다는 내부 규칙을 적용합니다. 예를 들어 PCTFREE 60 PCTUSED 50으로 설정하면 합이 110이 되어 에러가 발생합니다. 이 규칙은 블록 내 공간 관리 로직에서 두 파라미터가 겹치지 않도록 보장하기 위해 존재합니다.

3. 문자열이나 NULL 등 비정수 값이 파라미터로 전달되는 경우

동적 SQL이나 스크립트를 통해 DDL을 실행할 때, 파라미터 바인딩 오류나 스크립트 변수 미초기화로 인해 숫자가 아닌 문자열 또는 빈 값이 PCTFREE/PCTUSED 자리에 전달될 수 있습니다. 특히 셸 스크립트나 Python, Java 기반 자동화 도구에서 DDL을 생성할 때 이런 문제가 자주 발생합니다. Oracle은 정수만을 허용하며 그 외의 타입은 모두 에러로 처리합니다.

해결 방법

원인 1 해결: 유효 범위 내의 값으로 수정

PCTFREE는 0~99, PCTUSED는 1~99 사이의 값으로 설정합니다.

-- 잘못된 예 (ORA-02211 발생)
CREATE TABLE employees (
    emp_id   NUMBER,
    emp_name VARCHAR2(100)
)
PCTFREE 100   -- 100은 허용되지 않음
PCTUSED 40;

-- 올바른 예
CREATE TABLE employees (
    emp_id   NUMBER,
    emp_name VARCHAR2(100)
)
PCTFREE 20
PCTUSED 40;

원인 2 해결: PCTFREE + PCTUSED 합이 100 미만이 되도록 조정

두 값의 합이 반드시 100 미만(최대 99)이 되어야 합니다.

-- 잘못된 예 (합이 110으로 ORA-02211 발생)
ALTER TABLE orders
    PCTFREE 60
    PCTUSED 50;   -- 60 + 50 = 110, 에러 발생

-- 올바른 예 (합이 80으로 정상)
ALTER TABLE orders
    PCTFREE 30
    PCTUSED 50;   -- 30 + 50 = 80, 정상 동작

-- 인덱스의 경우 PCTUSED는 적용되지 않으므로 주의
ALTER INDEX idx_orders_date
    REBUILD
    PCTFREE 10;

원인 3 해결: 동적 SQL 실행 전 값 유효성 검증

스크립트나 프로시저 내에서 동적으로 DDL을 실행할 때는 반드시 값 범위를 사전에 검증합니다.

-- PL/SQL을 이용한 안전한 동적 DDL 실행 예제
DECLARE
    v_pctfree  NUMBER := 20;
    v_pctused  NUMBER := 40;
    v_sql      VARCHAR2(1000);
BEGIN
    -- 유효성 검증
    IF v_pctfree < 0 OR v_pctfree > 99 THEN
        RAISE_APPLICATION_ERROR(-20001, 'PCTFREE 값은 0~99 사이여야 합니다.');
    END IF;

    IF v_pctused < 1 OR v_pctused > 99 THEN
        RAISE_APPLICATION_ERROR(-20002, 'PCTUSED 값은 1~99 사이여야 합니다.');
    END IF;

    IF (v_pctfree + v_pctused) >= 100 THEN
        RAISE_APPLICATION_ERROR(-20003, 'PCTFREE + PCTUSED 합은 100 미만이어야 합니다.');
    END IF;

    -- 검증 통과 후 DDL 실행
    v_sql := 'CREATE TABLE safe_table ('
          || '    col1 NUMBER, '
          || '    col2 VARCHAR2(100)'
          || ') PCTFREE ' || v_pctfree
          || ' PCTUSED ' || v_pctused;

    EXECUTE IMMEDIATE v_sql;
    DBMS_OUTPUT.PUT_LINE('테이블 생성 완료.');
EXCEPTION
    WHEN OTHERS THEN
        DBMS_OUTPUT.PUT_LINE('에러 발생: ' || SQLERRM);
END;
/

현재 테이블의 PCTFREE/PCTUSED 값 확인 방법

-- 테이블의 스토리지 파라미터 확인
SELECT table_name,
       pct_free,
       pct_used,
       ini_trans,
       max_trans
FROM   user_tables
WHERE  table_name = 'EMPLOYEES';

-- 인덱스의 PCTFREE 확인
SELECT index_name,
       pct_free,
       status
FROM   user_indexes
WHERE  table_name = 'EMPLOYEES';

예방 방법

1. DDL 스크립트에 표준 스토리지 템플릿 적용

프로젝트 또는 조직 내에서 표준 스토리지 파라미터 템플릿을 정의하고, 모든 DDL 스크립트가 이 템플릿을 기반으로 생성되도록 가이드라인을 수립하세요. 예를 들어 OLTP 테이블은 PCTFREE 20 PCTUSED 40, DW 테이블은 PCTFREE 5 PCTUSED 60과 같이 용도별로 표준값을 정해두면 실수로 잘못된 값을 입력하는 상황을 크게 줄일 수 있습니다. 스크립트 자동화 시에는 반드시 위의 PL/SQL 유효성 검증 로직을 포함시키는 것을 권장합니다.

-- 조직 표준 템플릿 예시 (OLTP 테이블)
CREATE TABLE new_table (
    col1 NUMBER        NOT NULL,
    col2 VARCHAR2(200) NOT NULL,
    col3 DATE          DEFAULT SYSDATE
)
TABLESPACE users
PCTFREE  20   -- 업데이트 여유 공간 20%
PCTUSED  40   -- 40% 미만 사용 시 재삽입 허용
INITRANS 2
MAXTRANS 255
STORAGE (
    INITIAL  1M
    NEXT     1M
    MINEXTENTS 1
    MAXEXTENTS UNLIMITED
);

2. CI/CD 파이프라인에서 DDL 사전 검증 단계 추가

데이터베이스 변경 관리(SCM) 또는 CI/CD 파이프라인에 DDL 스크립트 정적 분석 단계를 추가하여 배포 전에 스토리지 파라미터 값의 유효성을 자동으로 검사하도록 구성하세요. Flyway, Liquibase 등의 툴과 커스텀 검증 스크립트를 결합하면 ORA-02211을 포함한 다양한 DDL 에러를 사전에 차단할 수 있습니다. 검증 실패 시 파이프라인이 자동으로 중단되도록 설정하면 운영 환경에서의 장애를 예방할 수 있습니다.

관련 에러

  • ORA-02207: INITRANS 또는 MAXTRANS 파라미터에 잘못된 값이 지정되었을 때 발생하며, ORA-02211과 동일한 DDL 스토리지 옵션 검증 과정에서 함께 확인해야 합니다.
  • ORA-02143: STORAGE 절에 잘못된 옵션이 지정된 경우 발생하며, INITIAL, NEXT, MAXEXTENTS 등의 값이 유효하지 않을 때 나타납니다.
  • ORA-01735: ALTER TABLE 명령에서 잘못된 옵션이 사용될 때 발생하며, 스토리지 파라미터 변경 시 문법 오류와 함께 자주 동반됩니다.
  • ORA-14024: 파티션 테이블에서 PCTFREE 또는 PCTUSED 값을 잘못 지정할 경우 발생하며, 파티션별 스토리지 옵션이 상위 테이블 정의와 충돌할 때 나타납니다.
DBMS 에러 코드 시리즈

주요 DBMS error code를 정리하는 시리즈입니다.
블로그 홈에서 다른 에러도 확인하세요.

본 포스트는 AI가 생성한 기술 가이드입니다. 운영 환경 적용 전 충분한 검토를 권장합니다.

댓글 남기기