PostgreSQL 0F001 오류 원인과 해결 방법 완벽 가이드

0F001
2026년 08월 05일 | DBMS Error 가이드

이 글에서 다루는 내용

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

0F001 invalid locator specification 는?

PostgreSQL 에러 코드 0F001: invalid locator specification은 LOB(Large Object, 대형 객체)를 참조하는 로케이터(locator) 값이 유효하지 않거나 존재하지 않는 OID를 가리킬 때 발생하는 에러입니다. 주로 lo_open(), lo_read(), lo_write(), lo_close(), loread(), lowrite() 등 PostgreSQL의 Large Object 관련 함수를 사용할 때 잘못된 OID 또는 만료된 Large Object 핸들을 전달하면 이 에러가 트리거됩니다. 애플리케이션 레이어에서 Large Object의 OID를 잘못 관리하거나, 트랜잭션 경계 밖에서 Large Object 핸들을 재사용하려는 경우에도 동일한 에러가 발생할 수 있습니다.

주요 발생 원인

1. 존재하지 않는 Large Object OID 참조

가장 흔한 원인으로, pg_largeobject 시스템 카탈로그에 실제로 존재하지 않는 OID를 lo_open() 등의 함수에 전달하는 경우입니다. 예를 들어, Large Object가 이미 lo_unlink()로 삭제되었는데 애플리케이션이 캐싱된 오래된 OID를 계속 사용하려 할 때 이 에러가 발생합니다. OID 값을 외부 테이블이나 변수에 저장해두고 참조할 때 동기화가 맞지 않으면 반드시 이 문제가 나타납니다.

2. 트랜잭션 외부에서 Large Object 핸들 사용

PostgreSQL의 Large Object 핸들(로케이터)은 트랜잭션 범위(transaction scope) 내에서만 유효합니다. 트랜잭션이 커밋되거나 롤백된 이후에 동일한 핸들을 재사용하려 하면 해당 핸들은 이미 무효화된 상태이므로 0F001 에러가 발생합니다. 특히 커넥션 풀링 환경에서 트랜잭션 경계가 불명확하게 관리될 때 이 문제가 자주 보고됩니다.

3. 잘못된 OID 타입 또는 NULL 값 전달

lo_open(oid, mode) 함수의 첫 번째 인자로 NULL 값이나 올바르지 않은 데이터 타입의 값을 전달하는 경우입니다. 애플리케이션 코드에서 OID 변수가 초기화되지 않았거나, 쿼리 결과에서 OID를 가져오는 로직에 버그가 있어 NULL 또는 0이 전달될 때 이 에러가 발생합니다. 특히 동적 SQL이나 ORM을 사용할 때 타입 바인딩 오류로 인해 이런 상황이 만들어지기도 합니다.

해결 방법

원인 1 해결: OID 존재 여부 사전 검증

Large Object 함수를 호출하기 전에 해당 OID가 pg_largeobject_metadata 카탈로그에 실제로 존재하는지 확인합니다.

-- Large Object OID 존재 여부 확인
SELECT oid
FROM pg_largeobject_metadata
WHERE oid = 123456;  -- 확인하려는 OID 값

-- PL/pgSQL 함수 내에서 안전하게 사용하는 예제
DO $$
DECLARE
    v_loid OID := 123456;
    v_fd   INTEGER;
    v_exists BOOLEAN;
BEGIN
    -- OID 유효성 사전 검사
    SELECT EXISTS (
        SELECT 1
        FROM pg_largeobject_metadata
        WHERE oid = v_loid
    ) INTO v_exists;

    IF NOT v_exists THEN
        RAISE EXCEPTION 'Large Object OID % does not exist.', v_loid;
    END IF;

    -- 유효한 경우에만 열기
    v_fd := lo_open(v_loid, x'40000'::int);  -- INV_READ = 0x40000
    PERFORM lo_close(v_fd);

    RAISE NOTICE 'Large Object % opened and closed successfully.', v_loid;
END;
$$;

원인 2 해결: 트랜잭션 블록 안에서 Large Object 핸들 사용

Large Object 작업은 반드시 명시적인 트랜잭션 블록 안에서 시작하고 종료해야 합니다.

-- 올바른 Large Object 사용 패턴 (트랜잭션 블록 내)
BEGIN;

DO $$
DECLARE
    v_loid OID;
    v_fd   INTEGER;
    v_data BYTEA;
BEGIN
    -- 새로운 Large Object 생성
    v_loid := lo_create(0);
    RAISE NOTICE 'Created Large Object OID: %', v_loid;

    -- 쓰기 모드로 열기 (INV_WRITE = 0x20000)
    v_fd := lo_open(v_loid, x'20000'::int);

    -- 데이터 쓰기
    PERFORM lowrite(v_fd, 'Hello, Large Object!'::bytea);

    -- 핸들 닫기 (같은 트랜잭션 내에서)
    PERFORM lo_close(v_fd);

    RAISE NOTICE 'Write complete. OID: %', v_loid;
END;
$$;

COMMIT;
-- 트랜잭션 커밋 후에는 위 핸들(v_fd)을 재사용하면 안 됨

-- 잘못된 패턴 예시 (에러 유발)
-- COMMIT 이후에 이전 핸들로 lo_close() 호출하면 0F001 발생

원인 3 해결: NULL 및 OID 값 방어 코드 추가

-- NULL 또는 0 OID 값 방어 처리
CREATE OR REPLACE FUNCTION safe_lo_open(p_loid OID, p_mode INTEGER)
RETURNS INTEGER AS $$
DECLARE
    v_fd INTEGER;
BEGIN
    -- NULL 체크
    IF p_loid IS NULL THEN
        RAISE EXCEPTION '0F001: Large Object OID cannot be NULL.';
    END IF;

    -- OID = 0 체크 (유효하지 않은 OID)
    IF p_loid = 0 THEN
        RAISE EXCEPTION '0F001: Large Object OID 0 is not valid.';
    END IF;

    -- 카탈로그 존재 여부 확인
    IF NOT EXISTS (
        SELECT 1 FROM pg_largeobject_metadata WHERE oid = p_loid
    ) THEN
        RAISE EXCEPTION '0F001: Large Object with OID % not found.', p_loid;
    END IF;

    -- 안전하게 오픈
    v_fd := lo_open(p_loid, p_mode);
    RETURN v_fd;

EXCEPTION
    WHEN OTHERS THEN
        RAISE EXCEPTION 'safe_lo_open failed: %', SQLERRM;
END;
$$ LANGUAGE plpgsql;

-- 함수 사용 예시
BEGIN;
SELECT safe_lo_open(123456, x'40000'::int);  -- INV_READ
COMMIT;

예방 방법

1. Large Object 라이프사이클을 테이블로 중앙 관리

Large Object의 OID를 별도의 관리 테이블에 저장하고, 삭제 시에는 반드시 해당 테이블에서도 레코드를 제거하는 방식으로 OID의 유효성을 항상 보장하세요. 트리거를 활용하면 pg_largeobject_metadata와의 정합성을 자동으로 유지할 수 있습니다.

-- Large Object 관리 테이블 예시
CREATE TABLE lo_registry (
    id          SERIAL PRIMARY KEY,
    lo_oid      OID NOT NULL UNIQUE,
    description TEXT,
    created_at  TIMESTAMPTZ DEFAULT NOW(),
    is_active   BOOLEAN DEFAULT TRUE
);

-- Large Object 삭제 시 자동으로 레지스트리 업데이트하는 함수
CREATE OR REPLACE FUNCTION deactivate_lo_registry()
RETURNS TRIGGER AS $$
BEGIN
    UPDATE lo_registry SET is_active = FALSE WHERE lo_oid = OLD.oid;
    RETURN OLD;
END;
$$ LANGUAGE plpgsql;

2. 예외 처리와 로깅을 통한 조기 감지

애플리케이션이나 PL/pgSQL 코드에서 Large Object 관련 작업에는 항상 EXCEPTION 블록을 추가하고, SQLSTATE가 0F001인 경우를 명시적으로 처리하세요. 에러 발생 시 로그에 OID 값과 호출 컨텍스트를 기록하면 추후 디버깅이 훨씬 쉬워집니다.

-- 예외 처리 패턴 예시
DO $$
DECLARE
    v_fd INTEGER;
BEGIN
    v_fd := lo_open(99999, x'40000'::int);
EXCEPTION
    WHEN invalid_locator_specification THEN  -- SQLSTATE '0F001'
        RAISE WARNING '[0F001] Invalid LO locator. OID=99999. Check pg_largeobject_metadata.';
    WHEN OTHERS THEN
        RAISE WARNING 'Unexpected error: % (SQLSTATE: %)', SQLERRM, SQLSTATE;
END;
$$;