오류 체계 — 코드 · 메시지 · 계층별 매핑

이 문서가 답하는 질문

• 이 확장의 오류에 SQLSTATE가 있는가? (요약: 사실상 없다)
• error! / .expect() / .unwrap()이 사용자에게 어떻게 보이는가?
• og_explain_error가 실제로 낼 수 있는 코드는?
• 같은 오류가 SQL / Bolt / Studio에서 각각 어떻게 보이는가?
• 어떤 실패가 오류가 아니라 NOTICE 또는 침묵인가?

1. 사실 — SQLSTATE 규율이 없다

engine/src/ 전체에서 ERRCODE, PgSqlErrorCode, ereport, sqlstate 를 쓰는 코드는 한 줄도 없다 (grep -rn 'ERRCODE\|PgSqlErrorCode\|ereport\|sqlstate' engine/src/ → engine/src/id.rs:31의 주석 한 줄만 매치).

모든 사용자 대면 오류는 두 경로 중 하나로 나온다.

귀결: 클라이언트는 SQLSTATE로 오류를 분류할 수 없다. "라벨 오타"와 "SPI 내부 실패"가 같은 코드다. → 12_improvements_api.md API-31.

이 공백을 메우기 위해 세 곳에서 각자 문자열 매칭을 한다:

2. 오류 매크로 사용 분포 (실측)

grep -rc 'error!(' engine/src/

panic!()은 테스트 모듈에만 존재한다 (engine/src/cypher/parser.rs:1146, engine/src/typeql/parser.rs:982, engine/src/adapters/rdf.rs:880 — 모두 #[cfg(test)] 안). 프로덕션 경로의 패닉은 전부 .expect() / .unwrap() 이다.

3. 오류 메시지 계층

3.1 A급 — 사람이 읽고 고칠 수 있는 메시지

교정 정보를 담고 있으며, 이 프로젝트가 잘하는 부분이다.

3.2 B급 — 원인은 알려주지만 교정은 없는 메시지

3.3 C급 — 내부 메시지가 사용자에게 그대로 노출되는 경우

.expect("…") 문자열이 그대로 ERROR 메시지가 된다. 사용자 관점에서 아무 의미가 없다.

가장 자주 만나게 되는 것: 같은 프로퍼티를 두 번 선언하면 property insert failed. "이미 선언되어 있다"는 정보가 없다 → 12_improvements_api.md API-31.

3.4 D급 — 컴파일된 SQL이 통째로 노출되는 경우

ERROR:  cypher execution failed: <postgres error>
--- compiled SQL ---
SELECT to_jsonb(...) FROM og_data.n_12 AS n1 CROSS JOIN LATERAL ...

(cypher/mod.rs:149)

디버깅에는 훌륭하지만 내부 스키마(테이블 이름, 컬럼 이름, 타입 id)를 전부 노출한다. Studio가 인증 없이 이걸 그대로 클라이언트에 전달한다 → 12_improvements_api.md API-31.

4. og_explain_error의 코드 체계

정의: engine/src/agent/mod.rs:261, 분류: engine/src/agent/mod.rs:294.

분류는 오류 메시지 문자열의 부분 일치이고, 순서대로 검사된다.

if msg.contains("unknown label")      { "UNKNOWN_LABEL" }
else if msg.contains("not defined")   { "UNBOUND_VARIABLE" }
else if msg.contains("unknown function") { "UNKNOWN_FUNCTION" }
else if msg.contains("not supported") { "UNSUPPORTED_SYNTAX" }
else                                  { "COMPILE_ERROR" }

4.1 코드별 도달 가능성 (검증됨)

4.2 UNKNOWN_LABEL이 도달 불가한 이유

grep -rn 'unknown label' engine/src/ 결과는 세 곳뿐이고 아무도 오류를 내지 않는다:

• engine/src/agent/mod.rs:295 — classify()의 검사 자체
• engine/src/agent/mod.rs:317 — suggestions()의 검사 자체
• engine/src/catalog/types.rs:203 — 주석

실제 동작: 존재하지 않는 라벨은 NOTICE 를 내고 "아무것도 매치하지 않음"으로 컴파일된다(engine/src/catalog/types.rs:168):

NOTICE:  label 'Persn' does not exist in graph 'default' — matching nothing. did you mean: Person

결정(Decision): 이것은 의도된 설계다 — Cypher에서 존재하지 않는 라벨은 오류가 아니고, 라벨을 만들기 전에 탐색하는 호출자가 이 동작에 의존한다 (catalog/types.rs:161).

하지만 그 결과 og_explain_error는 라벨 오타에 {"ok": true}를 반환한다. 라벨 오타를 잡으라고 만든 함수가 그것을 잡지 못한다.

4.3 UNSUPPORTED_SYNTAX가 도달 불가한 이유

grep -rn 'not supported' engine/src/ 결과:

Cypher 컴파일러가 내는 오류 중 "not supported"를 포함하는 것은 없다. compile.rs:1178의 property access is only supported on pattern variables는 "only supported"이지 "not supported"가 아니다.

4.4 ⚠️ 원문 문서와의 불일치

docs/cypher.md:249은 이렇게 적고 있다:

SELECT og_explain_error('kb', 'MATCH (a) RETURN nosuchfunction(a)');
-- {"ok": false, "code": "UNSUPPORTED_SYNTAX", "message": "unknown function …"}

classify()가 "unknown function"을 먼저 검사하므로 실제 값은 "UNKNOWN_FUNCTION" 이다. 문서 예제가 틀렸다.

docs/cypher.md:295은 이렇게 적고 있다:

ERROR:  unknown label 'Persn' in graph 'social'. did you mean: Person

코드에 그런 ERROR가 존재하지 않는다. 실제로는 위 §4.2의 NOTICE다.

→ 12_improvements_api.md API-10.

5. 계층별 매핑 — 같은 오류가 어떻게 보이는가

예: MATCH (p:Person) RETURN nosuchfn(p)

5.1 Bolt의 Neo4j 코드 매핑 (문자열 기반)

정의: bolt/src/session.rs:578

별도 경로:

문제점 (확인됨)

• graph 'x' does not exist(그래프 없음)와 type 'x' does not exist(타입 없음)가 둘 다 DatabaseNotFound 가 된다. 후자는 데이터베이스 문제가 아니다.
• "expected"는 매우 흔한 단어라 파서와 무관한 오류도 SyntaxError가 될 수 있다.
• "unknown label" 분기는 §4.2에 따라 영원히 매치되지 않는다.

6. ⚠️ 오류가 아닌 실패 — 침묵과 NOTICE

계약 관점에서 가장 위험한 부분이다. 아래는 호출자가 감지할 수 없는 실패들이다.

필수 규칙: 위 표의 동작을 성공으로 해석하지 말 것. 특히 UNION, og_typeql(_params), og_apply_role(max_rows)는 있는 줄 알고 쓰면 조용히 잘못 동작한다.

7. 감사 로그의 error_code 컬럼

이름과 달리 코드가 아니라 메시지 앞 200자가 들어간다 (cypher/mod.rs:122, typeql/mod.rs:115):

err.map(|e| e.chars().take(200).collect::<String>()).into()

SELECT at, lang, rows_out, duration_ms, error_code
  FROM og_data.og_audit
 WHERE error_code IS NOT NULL
 ORDER BY at DESC LIMIT 20;

error_code가 NULL이면 성공이다. 이것이 현재 유일하게 신뢰할 수 있는 성공/실패 구분자다.

⚠️ 감사 기록은 og_cypher / og_typeql 호출에서 파싱 실패 시에만 오류를 기록한다. 컴파일 실패나 실행 실패는 error!로 즉시 중단되어 audit(..., None) 이 호출되지 않는다(cypher/mod.rs:140, :149) → 12_improvements_api.md API-31.

8. 클라이언트를 위한 실용 지침

8.1 오류를 분류하는 방법 (현재 가능한 것)

-- 1) 실행 전에 파싱 검증 (오류를 던지지 않음)
SELECT og_cypher_check('MATCH (p:Person) RETURN p');
-- {"ok": true, "clauses": 2, "write": false}

-- 2) 컴파일 검증 + 구조화된 코드 (오류를 던지지 않음)
SELECT og_explain_error('default', 'MATCH (p:Person) RETURN p');
-- {"ok": true}

-- 3) 라벨 존재 여부는 별도로 확인해야 한다 (2)가 잡지 않는다
SELECT name FROM og_type_view WHERE graph = 'default';

8.2 재시도 판단

9. 금지 / 필수

• 금지: SQLSTATE로 이 확장의 오류를 분류하려 하지 말 것 — 거의 전부 XX000이다.
• 금지: og_explain_error의 {"ok": true}를 "질의가 옳다"로 읽지 말 것. 라벨 오타는 잡히지 않는다(§4.2).
• 금지: UNKNOWN_LABEL / UNSUPPORTED_SYNTAX 코드를 처리하는 분기를 작성하지 말 것 — 현재 코드에서는 도달하지 않는다.
• 금지: Studio의 HTTP 400을 "클라이언트 잘못"으로 해석하지 말 것.
• 금지: og_data.og_audit.error_code를 코드로 파싱하지 말 것 — 메시지 앞 200자다.
• 필수: 실행 전 검증은 og_cypher_check() + og_explain_error() + 라벨 존재 확인의 세 단계로 할 것.
• 필수: §6의 "조용한 실패" 표를 클라이언트 구현 전에 읽을 것.
• 필수: cypher execution failed: … 오류가 컴파일된 SQL 전문을 담는다는 점을 감안해, 사용자에게 그대로 노출하지 말 것.

10. 관련 문서

• Cypher 문법 경계와 거부 메시지 → 03_cypher.md §4
• TypeQL 거부 메시지 → 04_typeql.md §5
• 에이전트 진단 함수 → 07_agent_interface.md §3
• Bolt 코드 매핑 → 09_neo4j_compat.md §5.7
• Studio 오류 응답 → 10_studio_http_api.md §2.3
• 개선 제안 → 12_improvements_api.md