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

0F001
2026년 10월 09일 | DBMS Error 가이드

이 글에서 다루는 내용

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

0F001 invalid locator specification 는?

PostgreSQL 에러 코드 0F001은 invalid locator specification, 즉 “잘못된 로케이터 명세”를 의미합니다. 이 에러는 주로 Large Object(대용량 객체)를 다루는 과정에서 유효하지 않은 OID(Object Identifier) 또는 잘못된 방식으로 로케이터를 참조할 때 발생합니다. 특히 lo_open(), lo_read(), lo_write(), lo_lseek(), lo_close() 등의 Large Object 관련 함수를 사용할 때 잘못된 파일 디스크립터나 존재하지 않는 OID를 전달하면 이 에러가 트리거됩니다.

주요 발생 원인

1. 유효하지 않은 Large Object OID 참조

가장 흔한 원인으로, pg_largeobject 시스템 카탈로그에 존재하지 않는 OID를 이용해 Large Object를 열려고 시도할 때 발생합니다. 예를 들어 이미 삭제된 Large Object의 OID를 애플리케이션이 캐싱하고 있다가 재사용하거나, 다른 데이터베이스 환경에서 가져온 OID 값을 그대로 사용하는 경우에 이 에러가 발생합니다. 트랜잭션이 롤백된 이후에도 OID 참조값을 유지하는 코드 패턴에서 특히 자주 나타납니다.

2. 잘못된 파일 디스크립터(fd) 사용

lo_open() 함수가 반환하는 파일 디스크립터(정수값)를 올바르게 관리하지 않을 때 발생합니다. 이미 lo_close()로 닫힌 파일 디스크립터를 다시 lo_read() 또는 lo_write()에 전달하거나, 트랜잭션 경계를 넘어서 파일 디스크립터를 재사용하려는 경우가 대표적입니다. PostgreSQL에서 Large Object 파일 디스크립터는 트랜잭션 범위 내에서만 유효하며, 트랜잭션이 종료되면 자동으로 무효화됩니다.

3. 권한 문제 또는 잘못된 접근 모드

lo_open() 함수 호출 시 INV_READ(262144) 또는 INV_WRITE(131072) 등의 접근 모드를 잘못 지정하거나, 해당 Large Object에 대한 접근 권한이 없는 경우에도 유사한 로케이터 관련 에러가 발생할 수 있습니다. 특히 다른 사용자가 소유한 Large Object에 대해 권한 없이 접근하거나, 읽기 전용으로 연 객체에 쓰기를 시도하는 코드 버그가 원인이 되기도 합니다. 이는 보안 정책이 강화된 운영 환경에서 더욱 빈번하게 나타납니다.

해결 방법

원인 1: 유효하지 않은 OID 확인 및 처리

Large Object 작업 전에 해당 OID가 실제로 존재하는지 반드시 검증하는 습관을 들여야 합니다.

-- Large Object OID가 존재하는지 사전 확인
SELECT COUNT(*) 
FROM pg_largeobject_metadata 
WHERE oid = 12345;

-- 존재하는 경우에만 접근하는 안전한 패턴 (PL/pgSQL 예시)
DO $$
DECLARE
    v_lo_oid OID := 12345;
    v_fd     INTEGER;
    v_exists INTEGER;
BEGIN
    -- OID 존재 여부 확인
    SELECT COUNT(*) INTO v_exists
    FROM pg_largeobject_metadata
    WHERE oid = v_lo_oid;

    IF v_exists = 0 THEN
        RAISE EXCEPTION 'Large Object OID % does not exist.', v_lo_oid;
    END IF;

    -- 안전하게 열기
    v_fd := lo_open(v_lo_oid, 262144); -- INV_READ
    -- ... 작업 수행 ...
    PERFORM lo_close(v_fd);
END;
$$;

-- 孤立된(orphan) Large Object 목록 확인 (참조되지 않는 LO 탐지)
SELECT lo.oid
FROM pg_largeobject_metadata lo
LEFT JOIN pg_attribute a ON a.atttypid = 'lo'::regtype::oid
WHERE a.attrelid IS NULL
LIMIT 20;

-- vacuumlo 도구를 사용하여 정리 (psql 외부 명령)
-- $ vacuumlo -v mydb

원인 2: 파일 디스크립터 올바른 관리

트랜잭션 내에서 파일 디스크립터의 생명주기를 명확히 관리해야 합니다.

-- 올바른 Large Object 읽기 패턴
BEGIN;

DO $$
DECLARE
    v_lo_oid  OID     := 16384;
    v_fd      INTEGER;
    v_data    BYTEA;
BEGIN
    -- lo_open은 반드시 트랜잭션 내에서 호출
    v_fd := lo_open(v_lo_oid, 262144); -- INV_READ = 262144

    IF v_fd < 0 THEN
        RAISE EXCEPTION 'Failed to open Large Object: invalid fd';
    END IF;

    -- 데이터 읽기
    v_data := loread(v_fd, 1024000); -- 최대 1MB 읽기

    RAISE NOTICE 'Read % bytes', octet_length(v_data);

    -- 반드시 명시적으로 닫기
    PERFORM lo_close(v_fd);

EXCEPTION
    WHEN OTHERS THEN
        -- 에러 발생 시에도 fd 정리 시도
        BEGIN
            PERFORM lo_close(v_fd);
        EXCEPTION WHEN OTHERS THEN
            NULL; -- 이미 닫혔거나 무효한 경우 무시
        END;
        RAISE;
END;
$$;

COMMIT;

-- Large Object 쓰기 올바른 패턴
BEGIN;

DO $$
DECLARE
    v_lo_oid OID;
    v_fd     INTEGER;
BEGIN
    -- 새 Large Object 생성
    v_lo_oid := lo_create(0); -- 0이면 자동 OID 할당
    RAISE NOTICE 'Created LO with OID: %', v_lo_oid;

    -- 쓰기 모드로 열기 (INV_WRITE = 131072)
    v_fd := lo_open(v_lo_oid, 131072);

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

    -- 닫기
    PERFORM lo_close(v_fd);

    RAISE NOTICE 'Successfully written to LO OID: %', v_lo_oid;
END;
$$;

COMMIT;

원인 3: 권한 및 접근 모드 점검

-- 현재 사용자의 Large Object 접근 권한 확인
SELECT lo_oid,
       pg_catalog.has_largeobject_privilege(lo_oid, 'SELECT') AS can_select,
       pg_catalog.has_largeobject_privilege(lo_oid, 'UPDATE') AS can_update
FROM (
    SELECT oid AS lo_oid
    FROM pg_largeobject_metadata
    LIMIT 10
) sub;

-- Large Object 소유권 확인 및 권한 부여
SELECT lomowner::regrole, oid
FROM pg_largeobject_metadata
WHERE oid = 12345;

-- 특정 사용자에게 Large Object 권한 부여
GRANT SELECT ON LARGE OBJECT 12345 TO myuser;
GRANT UPDATE ON LARGE OBJECT 12345 TO myuser;

-- 읽기+쓰기 모드 동시 사용 (INV_READ | INV_WRITE = 393216)
DO $$
DECLARE
    v_fd INTEGER;
BEGIN
    v_fd := lo_open(12345, 393216); -- INV_READ(262144) | INV_WRITE(131072)
    -- 읽기 후 쓰기 가능
    PERFORM lo_close(v_fd);
END;
$$;

예방 방법

1. Large Object 작업을 래핑하는 안전한 함수 작성

반복적으로 사용하는 Large Object 조작 로직을 별도의 PL/pgSQL 함수로 캡슐화하여, OID 유효성 검증, 파일 디스크립터 관리, 예외 처리를 일관되게 적용하는 것이 좋습니다. 아래와 같이 안전하게 Large Object를 읽는 래퍼 함수를 만들어 두면 실수로 인한 0F001 에러를 대폭 줄일 수 있습니다.

CREATE OR REPLACE FUNCTION safe_lo_read(p_lo_oid OID, p_max_bytes INTEGER DEFAULT 10485760)
RETURNS BYTEA
LANGUAGE plpgsql
AS $$
DECLARE
    v_fd     INTEGER := -1;
    v_result BYTEA;
    v_exists INTEGER;
BEGIN
    -- OID 유효성 검증
    SELECT COUNT(*) INTO v_exists
    FROM pg_largeobject_metadata
    WHERE oid = p_lo_oid;

    IF v_exists = 0 THEN
        RAISE EXCEPTION 'LO OID % not found (0F001 prevention)', p_lo_oid
            USING ERRCODE = '0F001';
    END IF;

    -- 읽기 모드로 열기
    v_fd := lo_open(p_lo_oid, 262144);

    IF v_fd < 0 THEN
        RAISE EXCEPTION 'lo_open failed for OID %', p_lo_oid;
    END IF;

    v_result := loread(v_fd, p_max_bytes);
    PERFORM lo_close(v_fd);

    RETURN v_result;
EXCEPTION
    WHEN OTHERS THEN
        IF v_fd >= 0 THEN
            BEGIN
                PERFORM lo_close(v_fd);
            EXCEPTION WHEN OTHERS THEN NULL;
            END;
        END IF;
        RAISE;
END;
$$;

2. 정기적인 고아(orphan) Large Object 정리 및 모니터링

Large Object는 참조하는 테이블 행이 삭제되어도 자동으로 삭제되지 않습니다. 따라서 주기적으로 vacuumlo 유틸리티 또는 커스텀 쿼리를 통해 고아 Large Object를 정리하고, pg_largeobject_metadata의 크기를 모니터링해야 합니다. 불필요한 OID가 누적되면 잘못된 참조로 인한 0F001 에러 가능성이 높아집니다.

-- 주기적 모니터링 쿼리: Large Object 총 개수 및 용량 확인
SELECT
    COUNT(DISTINCT loid)             AS total_large_objects,
    SUM(octet_length(data))          AS total_bytes,
    pg_size_pretty(SUM(octet_length(data))::BIGINT) AS total_size
FROM pg_largeobject;

-- 30일 이상 된 Large Object 목록 (정리 대상 후보)
-- (생성 시각은 별도 메타 테이블로 관리 권장)