7. 문제가 생겼을 때

이 장을 마치면: 흔한 에러는 스스로 풀고, 못 푸는 문제는 증거를 지킨 채 올바르게 넘긴다.

소요: 필요할 때

7.1 에러 읽는 법

어디에 나오나

찾는 법 — 에러 문구의 일부(예: jq is required)로 이 장을 검색해 GDB- 항목으로 간다.

조치 등급

7.2 증상 지도

설치가 안 된다 ────────────────── 화면의 [ERROR] · ERROR: 문구 ───▶ GDB-INSTALL-001 ~ 003 · 005
다시 설치 · 업그레이드 뒤 설정이 사라졌다 ────────────────────────▶ GDB-INSTALL-004
기동이 안 된다 ────────────────── gritdb-start 출력 ──────────────▶ GDB-BOOT-001 ~ 006
테이블 등록이 안 된다 ────────────────────────────────────────────▶ GDB-RUNTIME-001
디스크가 찼다 · 파일을 못 연다 ───────────────────────────────────▶ GDB-RUNTIME-002 · 003
프로세스가 죽었다 · 멈췄다 · 데이터가 이상하다 ───────────────────▶ GDB-RUNTIME-004 → 7.4
정지 후 경고가 남는다 · 정지가 끝나지 않는다 ─────────────────────▶ GDB-SHUTDOWN-001 · 002

7.3 자주 만나는 에러

GDB-INSTALL-001 · root 로 설치 실행

증상 — 설치 화면

▶ 3.1 Initializing PostgreSQL data directory               ... FAIL

Install failed at step: 3.1 Initializing PostgreSQL data directory
See full log at: /root/gritdb1/log/install_gritdb_<일시>.log
  | ERROR: running as root: --user <service-account> is required (initdb refuses root).

원인: PostgreSQL은 root로 데이터 디렉토리를 만들지 않는다.

조치

1. /root/gritdb1은 방금 실패한 설치가 만든 디렉토리로, 데이터가 없다. root가 삭제한다.
2. su - gritdb
3. 3장 설치를 다시 한다. root로 설치해야 하는 사정이 있으면 Admin 2장을 본다.

등급: L1 · 성격: 절차

GDB-INSTALL-002 · jq 없음

증상

[ERROR] jq is required to read the manifest. Install jq first.

원인: 설치 스크립트가 제품 정보(manifest.json)를 읽는 데 jq가 필요하다.

조치

1. root가 OS 설치 매체나 기관 내부 저장소에서 jq를 설치한다(Ubuntu에서는 apt install jq).
2. 설치 명령을 다시 실행한다.

등급: L1 · 성격: 환경

GDB-INSTALL-003 · 반입 파일 무결성 실패

증상 — 셋 중 하나

gritdb-<...>.tar.gz: FAILED
sha256sum: WARNING: 1 computed checksum did NOT match

ERROR: hash mismatch: <파일>
ERROR: dist verification FAILED. Do not install this tree.

  <파일> missing!  FAIL

원인: 전송 중 손상, 다른 버전의 SHA256SUMS, 압축을 푼 뒤의 파일 변경.

조치

1. 설치를 멈춘다.
2. 압축을 푼 디렉토리(~/pkg/gritdb-*/)를 삭제한다.
3. 설치 파일과 SHA256SUMS를 다시 받는다. SHA256SUMS는 설치 파일과 다른 경로로 받는다.
4. 2장 2.3부터 다시 한다.

등급: L1 · 성격: 환경

GDB-INSTALL-004 · postgresql.conf 관리 블록 훼손

증상 — 다시 설치하거나 업그레이드한 뒤 postgresql.conf에 넣어 둔 설정이 사라졌다. 설치 화면에는 오류가 없다.

원인: 관리 블록의 시작 표식 줄이나 끝 표식 줄을 손으로 지우거나 고친 채 설치 명령을 다시 실행했다.

판별 — 설치나 업그레이드 전에도 같은 명령으로 확인한다.

grep -n "gritdb managed" ~/gritdb1/datafiles/pgdata/postgresql.conf

아래 두 줄이 한 번씩 나오면 정상이다.

<줄 번호>:# >>> gritdb managed begin
<줄 번호>:# <<< gritdb managed end

조치

1. 설치나 업그레이드 전이면 빠지거나 바뀐 표식 줄을 위 모양 그대로 되돌린 뒤 설치 명령을 실행한다. 시작 표식은 블록 첫 줄이고, 끝 표식은 블록 마지막 줄 다음 줄이다.
2. 이미 설정이 사라졌으면 사라진 설정을 ALTER SYSTEM으로 다시 넣는다(Admin 5장).
3. 무엇이 사라졌는지 모르면 7.4로 문의한다.

등급: L1 · 성격: 절차

GDB-INSTALL-005 · 설치 경로가 너무 김

증상

[ERROR] Prefix path is too deep: socket path would exceed the 108-byte unix socket limit.
[ERROR] Choose a shorter --prefix (e.g. $HOME/gritdb1).

원인: 설치 경로 뒤에 /run/grit_admin.sock을 붙인 경로가 운영체제 한도를 넘는다. 설치 경로는 80자 이하여야 한다.

조치: 옵션 없이 표준 경로로 설치한다. 홈 디렉토리 경로 자체가 길면 Admin 2장을 보고 짧은 경로에 설치한다.

등급: L1 · 성격: 절차

GDB-BOOT-001 · 설치되지 않은 경로에서 기동

증상

ERROR: not an installed GritDB tree (missing .gritdb_installed): <경로>
       Run install_gritdb.sh first.
[ERROR] Run install_gritdb.sh first.

발생 조건: 압축만 푼 디렉토리(~/pkg/gritdb-*/)의 bin/gritdb-start를 실행했거나, 설치가 중간에 실패했다.

원인: 설치 완료 표식 .gritdb_installed가 없는 경로라 기동 스크립트가 거부한다.

조치

1. 메시지의 <경로>를 본다.
2. ~/pkg/...이면 ~/gritdb1/bin/gritdb-start로 다시 실행한다.
3. ~/gritdb1이면 설치가 끝나지 않았다. 이때는 3장 설치를 다시 한다.

등급: L1 · 성격: 절차

GDB-BOOT-002 · 이미 실행 중

증상

[WARN] GritAdmin is already running (lock held: /home/gritdb/gritdb1/run/gritdb.lock)
[WARN] Use gritdb-stop to stop it first

원인: GritDB가 이미 떠 있다.

조치: 4장 4.3으로 정상인지 확인한다. 다시 띄우려면 4.6으로 재시작한다.

등급: L1 · 성격: 절차

GDB-BOOT-003 · pg_ctl 로 띄운 PostgreSQL 이 60초 뒤 종료

증상: pg_ctl start로 띄운 PostgreSQL이 약 60초 뒤 스스로 내려간다. log/postgresql.log에 GritDB 공유 메모리 연결 실패가 남는다.

원인: 감독 프로세스(grit_admin) 없이 기동했다. 금지 1에 해당한다.

조치

1. 1분쯤 기다린다. PostgreSQL이 스스로 내려간다.
2. 4장 4.3의 1번 명령을 실행해 출력이 없는지 확인한다. 2분이 지나도 남아 있으면 7.4를 본다.
3. ~/gritdb1/bin/gritdb-start

등급: L1 · 성격: 절차

GDB-BOOT-004 · glibc 버전 미달

증상 — 설치나 기동 중

<...>/libc.so.6: version `GLIBC_2.<n>' not found (required by <...>)

원인: 서버의 glibc가 GritDB 요구 버전보다 낮다.

판별: 2장 점검표의 4번으로 확인한다.

조치: 이 서버에는 설치할 수 없다. 요구 버전 이상의 OS로 바꾼다.

등급: L1 · 성격: 환경

GDB-BOOT-005 · 기동 중 감독 프로세스 종료

증상 — 둘 중 하나

[ERROR] GritAdmin process exited unexpectedly during startup
[ERROR] Check logs: /home/gritdb/gritdb1/log/grit_admin_stdout.log
[ERROR] Check logs: /home/gritdb/gritdb1/log/grit_admin_main.log

[ERROR] GritAdmin process exited during initialization
[ERROR] Check logs: /home/gritdb/gritdb1/log/grit_admin_main.log

판별 — 세 로그의 끝부분을 본다.

tail -20 ~/gritdb1/log/grit_admin_stdout.log
grep "\]\[ERROR\]\[" ~/gritdb1/log/grit_admin_main.log | tail -20
tail -20 ~/gritdb1/log/postgresql.log

등급: 판별 결과에 따라 L1~L3

GDB-BOOT-006 · pgdata 만 바꾼 뒤 기동 불가

증상: 기동이 실패하고, 로그에 ResolveStartLsn과 unreadable이 함께 보인다.

발생 조건: datafiles/pgdata만 지우고 다시 만들었거나, 다른 곳의 pgdata로 바꿨다(금지 2).

원인: datafiles/checkpoint가 가리키는 지점이 새 pgdata에 없다.

조치 — 데이터를 지켜야 하는지에 따라 다르다.

1. 운영 환경이고 데이터가 중요하면 이 상태 그대로 두고 7.4로 문의한다.

2. 시험 환경이고 데이터를 버려도 되면 재초기화한다. 기존 데이터는 이름만 바뀌어 남는다(Admin 3장).

   cd ~/pkg/gritdb-*/
   ./install_gritdb.sh --reinit-data
   

등급: 운영은 L3, 시험은 L2 · 성격: 절차

GDB-RUNTIME-001 · 테이블 등록 거부

증상 — psql

ERROR:  Table public.<테이블> must have REPLICA IDENTITY FULL. Current setting: DEFAULT. Run: ALTER TABLE public.<테이블> REPLICA IDENTITY FULL;

또는

ERROR:  Relation public.<테이블> not found

원인: 테이블이 등록 조건(REPLICA IDENTITY FULL)을 충족하지 않거나, 스키마나 테이블 이름에 오타가 있다.

조치

1. 첫 번째 에러가 나오면 안내된 ALTER TABLE ... REPLICA IDENTITY FULL;을 실행하고 다시 등록한다.
2. 두 번째 에러가 나오면 register_gritsurfer_table('<스키마>', '<테이블>')의 이름을 고친다.

등급: L1 · 성격: 절차

GDB-RUNTIME-002 · 디스크 부족

증상: 로그나 SQL 화면에 No space left on device가 나오거나, 5장 점검 3번의 사용률이 100%에 가깝다.

판별

df -h ~/gritdb1/datafiles ~/gritdb1/log
du -sh ~/gritdb1/datafiles/* ~/gritdb1/log

조치

1. GritDB 밖의 파일을 정리하거나 볼륨을 늘려 공간을 확보한다.
2. ⚠ datafiles/ 안의 파일은 지우지 않는다(금지 2). 복제 슬롯도 지우지 않는다(금지 3).
3. log/가 크면 Admin 9장 절차로 정리한다.
4. datafiles/pgdata/pg_wal이 크면 지우지 말고 7.4로 문의한다.
5. 공간을 확보한 뒤 gritdb-stop → gritdb-start를 실행한다. 응답 없이 멈춰 있으면 재기동 전에 7.4를 본다.

등급: L2 · 성격: 환경

GDB-RUNTIME-003 · 파일 열기 한도 초과

증상: 로그에 Too many open files가 나온다.

판별

ulimit -n

조치

1. root가 gritdb 계정의 한도를 65536 이상으로 올린다(Admin 1장).
2. gritdb 계정으로 다시 로그인해 ulimit -n을 확인한다.
3. gritdb-stop → gritdb-start
4. 한도를 올린 뒤에도 다시 나오면 7.4로 문의한다.

등급: L2 · 성격: 환경

GDB-RUNTIME-004 · 프로세스 종료 · 무응답 · 데이터 이상

증상 — 하나라도 해당

• 5장 점검 1번에서 프로세스가 4개보다 적다.
• SQL이 응답하지 않는다.
• log/GRIT_SURFER_ASSERT.log에 새 기록이 생겼다.
• 조회 결과가 예상과 다르다.

원인: 엔진 내부 오류다. 원인 분석은 지원 조직이 한다.

판별 — 먼저 최근 재초기화 흔적을 본다.

ls -d ~/gritdb1/datafiles.old-* 2>/dev/null

• 출력이 있으면 누군가 재초기화해 이전 데이터가 이름만 바뀌어 남아 있을 수 있다. 이때는 Admin 3장을 보고 복원을 검토한다.
• 출력이 없으면 조치로 간다.

조치: 7.4 절차를 따른다. 재기동이나 재초기화보다 자료 수집이 먼저다.

등급: L3 · 성격: 엔진

GDB-SHUTDOWN-001 · 정지 후 공유 메모리 잔여

증상 — gritdb-stop 끝부분

[WARN] POSIX shared memory segments remaining: <개수> (see /dev/shm, suffix _<인스턴스 ID>)
[WARN] Remove them manually only when no GritDB process is running

판별 — GritDB가 완전히 내려갔는지 본다.

pgrep -u gritdb -l -x 'GritAdmin|GritSurfer|GritCatalog|postgres'

출력이 없으면 완전히 내려간 상태다.

조치 — 판별 출력이 없을 때만 한다.

ID=$(~/gritdb1/bin/grit_instance_id ~/gritdb1)
ls /dev/shm | grep "_${ID}$"
rm -f /dev/shm/*_"${ID}"

• 이 설치본의 인스턴스 ID로 끝나는 것만 지운다. 다른 GritDB 설치본의 공유 메모리는 건드리지 않는다.
• 프로세스가 남아 있으면 지우지 않는다. 이때는 7.4를 본다.
• [WARN] Killing orphaned ...는 gritdb-stop이 남은 프로세스를 정리했다는 뜻이다. 판별 명령으로 한 번 더 확인한다.

등급: L1 · 성격: 환경

GDB-SHUTDOWN-002 · 정지가 끝나지 않음

증상: gritdb-stop이 Sending: grit_admin_client stop 뒤 오래 멈춰 있다. 또는 끝부분에 [WARN] Client command failed: ERROR stop failed …와 [WARN] Falling back to direct signal...이 보인다.

원인: 정상 정지는 실행 중인 문장이 끝나기를 최대 5분 기다린다. 열린 세션(쉬는 세션 포함)이 남아 있으면 약 30초 뒤 즉시 정지로 넘어간다.

판별 — 다른 터미널에서 남은 세션을 본다. 사용자 이름과 DB 이름이 보이는 줄이 접속 세션이다.

ps -u gritdb -o pid,args | grep "postgres: "

조치

1. 접속 중인 응용 프로그램을 먼저 끝낸다. 남은 세션을 끊으려면 Admin 4.2를 본다.
2. 끝낼 수 없으면 그대로 기다린다. 그러면 정지가 즉시 정지로 넘어간다. 진행 중인 작업이 끊기고, 다음 기동 때 복구를 거친다.

• 정지가 진행 중일 때 다른 터미널에서 gritdb-stop --quick을 실행해도 앞의 정지가 끝날 때까지 기다린다.

등급: L1 · 성격: 절차

7.4 풀리지 않을 때 — 자료 수집과 문의

1. 멈춘다 — 재초기화(--reinit-data), datafiles/ 파일 삭제, 복제 슬롯 삭제를 하지 않는다. 이런 작업을 하면 원인을 밝힐 증거가 사라진다.

2. 무응답이면 먼저 연락한다 — 멈춘 상태에서만 얻을 수 있는 정보가 있다. 재기동 전에 지원 조직과 통화한다.

3. 기록한다 — 발생 시각, 직전 작업, 화면의 에러 문구, 해당 GDB- 번호

4. 수집한다

   cd ~
   S=gritdb_support_$(date +%Y%m%d_%H%M%S)
   mkdir -p "$S"
   { date; uname -a; free -g; df -h; ulimit -a; } > "$S/system.txt" 2>&1
   for p in $(cut -d: -f2 ~/gritdb1/run/grit_admin.pid 2>/dev/null); do echo "== $p"; cat /proc/$p/limits; done >> "$S/system.txt" 2>&1
   ps -u gritdb -o pid,etime,args > "$S/process.txt" 2>&1
   ls -l /dev/shm > "$S/shm.txt" 2>&1
   cp ~/gritdb1/share/gritdb/manifest.json ~/gritdb1/datafiles/pgdata/postgresql.conf ~/gritdb1/datafiles/pgdata/postgresql.auto.conf ~/gritdb1/config/grit_*.config "$S/" 2>/dev/null
   tar -czf "$S.tar.gz" "$S" -C ~/gritdb1 log
   ls -lh "$S.tar.gz"
   

   • core 파일이 생겼으면 위치를 함께 알린다. 저장 위치는 cat /proc/sys/kernel/core_pattern으로 확인한다.

5. ⚠ 반출 전에 검토한다 — 로그와 설정에 SQL 원문, 데이터 값, 경로가 들어 있을 수 있다. 기관 반출 규정에 따라 검토하고 마스킹한 뒤 전달한다. 가린 묶음($S.masked.tar.gz)은 Admin 9장을 본다. 가리지 않은 $S.tar.gz는 보내지 않는다.

6. 문의한다 — 문의처는 Datagrit이다. 총판이나 파트너를 통해 샀으면 그 회사에 문의한다. 수집 파일과 3번 기록을 전달한다.

7. 재기동 — 수집을 끝낸 뒤 서비스 복구가 급하면 gritdb-stop → gritdb-start를 실행한다. 재초기화는 지원 조직이 지시할 때만 한다.

더 알아보기

• 에러 전체 목록, 심층 진단, 수집 절차 상세는 TroubleShooting을 본다.