PostgreSQL 58P01 오류 원인과 해결 방법 완벽 가이드

58P01
2026년 07월 21일 | DBMS Error 가이드

이 글에서 다루는 내용

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

58P01 undefined file 는?

PostgreSQL 에러 코드 58P01 undefined file은 데이터베이스 서버가 특정 작업을 수행하는 데 필요한 파일을 파일 시스템에서 찾을 수 없을 때 발생합니다. 이 에러는 주로 데이터 파일, 설정 파일, 또는 확장(extension) 관련 라이브러리 파일이 누락되거나 손상되었을 때 나타납니다. 테이블스페이스 이동, 백업 복원 실패, 또는 OS 레벨에서의 파일 삭제 등 다양한 시나리오에서 발생할 수 있으며, 즉각적인 조치가 필요한 심각한 에러입니다.

주요 발생 원인

1. 테이블스페이스(Tablespace) 경로 불일치 또는 파일 누락

테이블스페이스는 PostgreSQL이 데이터 파일을 저장하는 물리적 디렉토리를 가리키는데, 해당 디렉토리가 삭제되거나 마운트 포인트가 변경된 경우 58P01 에러가 발생합니다. 특히 스토리지 장애, 디스크 교체, 또는 서버 마이그레이션 이후 테이블스페이스 심볼릭 링크가 깨진 경우 이 에러를 자주 마주치게 됩니다. 테이블스페이스 경로가 올바른지, 해당 디렉토리가 실제로 존재하는지 반드시 확인해야 합니다.

2. 확장(Extension) 관련 공유 라이브러리 파일 누락

CREATE EXTENSION 또는 확장을 사용하는 함수를 호출할 때, PostgreSQL은 해당 확장의 .so(공유 라이브러리) 파일을 $libdir 경로에서 찾습니다. PostgreSQL 버전 업그레이드 이후 이전 버전의 확장 라이브러리가 새 버전 디렉토리에 복사되지 않았거나, OS 패키지 관리자로 패키지를 제거한 경우 이 에러가 발생합니다. pg_config --pkglibdir 명령으로 라이브러리 경로를 확인하고 누락된 .so 파일을 복구해야 합니다.

3. 데이터 파일(Relation File) 직접 삭제 또는 손상

PostgreSQL은 각 테이블과 인덱스에 대해 base/ 디렉토리 하위에 OID(Object Identifier) 기반의 파일을 생성하여 데이터를 저장합니다. 운영자 실수로 pg_relation_filepath() 함수가 반환하는 경로의 파일을 직접 삭제하거나, 파일 시스템 오류로 인해 해당 파일이 손상된 경우 해당 테이블에 접근 시 58P01 에러가 발생합니다. 이 경우 백업을 통한 복구가 필요하며, 백업이 없다면 데이터 손실이 불가피할 수 있습니다.

해결 방법

원인 1 해결: 테이블스페이스 경로 확인 및 복구

먼저 현재 등록된 테이블스페이스와 실제 경로를 확인합니다.

-- 현재 테이블스페이스 목록 및 경로 확인
SELECT spcname, pg_tablespace_location(oid) AS location
FROM pg_tablespace;

-- 특정 테이블이 어떤 테이블스페이스에 있는지 확인
SELECT schemaname, tablename, tablespace
FROM pg_tables
WHERE tablespace IS NOT NULL;

-- 테이블스페이스 경로 변경 (파일 이동 후)
ALTER TABLESPACE old_tablespace RENAME TO backup_tablespace;

-- 새 경로로 테이블스페이스 재생성
CREATE TABLESPACE new_tablespace LOCATION '/new/valid/path/to/tablespace';

-- 테이블을 새 테이블스페이스로 이동
ALTER TABLE my_table SET TABLESPACE new_tablespace;

OS 레벨에서 심볼릭 링크를 확인하고 복구합니다.

-- pg_tblspc 디렉토리 내 심볼릭 링크 확인을 위한 경로 조회
SELECT oid, spcname, pg_tablespace_location(oid)
FROM pg_tablespace
WHERE spcname NOT IN ('pg_default', 'pg_global');

# 실제 심볼릭 링크 상태 확인 (OS 명령어)
ls -la $PGDATA/pg_tblspc/

# 깨진 심볼릭 링크 재생성 예시
ln -s /new/valid/path/to/tablespace $PGDATA/pg_tblspc/<OID>

원인 2 해결: 확장 라이브러리 복구

-- 현재 설치된 확장 목록 확인
SELECT name, default_version, installed_version, comment
FROM pg_available_extensions
WHERE installed_version IS NOT NULL;

-- 문제가 되는 확장 확인
SELECT extname, extversion
FROM pg_extension;

-- 라이브러리 경로 확인 (psql에서 실행)
SHOW dynamic_library_path;

-- 확장 재설치 시도 (라이브러리 파일 복구 후)
DROP EXTENSION IF EXISTS problematic_extension CASCADE;
CREATE EXTENSION problematic_extension;

-- 확장의 실제 라이브러리 파일 위치 확인
SELECT proname, probin
FROM pg_proc
WHERE probin IS NOT NULL
LIMIT 10;

# 패키지 매니저로 확장 재설치 (Ubuntu/Debian 기준)
sudo apt-get install --reinstall postgresql-16-postgis-3

# 라이브러리 파일 존재 여부 확인
ls -la $(pg_config --pkglibdir)/

원인 3 해결: 데이터 파일 경로 확인 및 복구

-- 테이블의 실제 파일 경로 확인
SELECT pg_relation_filepath('my_table');

-- 파일 존재 여부 확인 (pg_filenode.map을 통해)
SELECT relname, relfilenode, reltablespace
FROM pg_class
WHERE relname = 'my_table';

-- 손상된 테이블 제거 후 백업에서 복구
-- 1단계: 더미 테이블로 파일노드 재생성
CREATE TABLE recovery_dummy (id int);
SELECT pg_relation_filepath('recovery_dummy');

-- 2단계: 백업 파일을 해당 경로에 복사 (OS 레벨)
-- 3단계: 더미 테이블 이름 변경으로 데이터 복구 시도
ALTER TABLE recovery_dummy RENAME TO my_table_recovered;

-- PITR(특정 시점 복구)를 위한 복구 설정 확인
SELECT pg_is_in_recovery();

-- 가장 최근 WAL 위치 확인
SELECT pg_current_wal_lsn();

예방 방법

1. 정기적인 파일 시스템 모니터링 및 데이터 무결성 검사

PostgreSQL 데이터 디렉토리의 파일 무결성을 정기적으로 모니터링하는 스크립트를 운영하고, pg_checksums(PostgreSQL 12 이상) 기능을 활성화하여 데이터 파일의 체크섬을 검증해야 합니다. 특히 테이블스페이스가 외부 스토리지나 NFS에 위치한 경우, 마운트 상태를 모니터링하는 알람을 설정하여 마운트 해제 시 즉시 대응할 수 있도록 해야 합니다.

-- PostgreSQL 12+ 체크섬 활성화 여부 확인
SHOW data_checksums;

-- 데이터베이스별 블록 오류 통계 확인 (pg_stat_database)
SELECT datname, checksum_failures, checksum_last_failure
FROM pg_stat_database
WHERE checksum_failures > 0;

2. 체계적인 백업 전략 수립 및 복구 훈련

pg_basebackup과 WAL 아카이빙을 결합한 PITR(Point-In-Time Recovery) 전략을 수립하고, 정기적으로 복구 훈련(Restore Drill)을 수행하여 실제 장애 상황에서 빠르게 대응할 수 있도록 합니다. 백업 파일의 유효성을 주기적으로 검증하고, 프로덕션과 동일한 환경에서 복구 테스트를 진행하는 것이 중요합니다.

-- WAL 아카이빙 상태 확인
SELECT archived_count, failed_count, last_archived_wal, last_failed_wal
FROM pg_stat_archiver;

-- 현재 WAL 수신 및 적용 상태 확인 (스탠바이 서버)
SELECT * FROM pg_stat_wal_receiver;