자주 만나는 연결 오류

자주 만나는 연결 오류와 해결

NeoSQL 의 실행 환경(Web App · Desktop · Offline) 특성상 발생할 수 있는 연결 오류와 해결 방법을 정리합니다.

연결 테스트에 실패하면 Test Connection 버튼 옆에 빨간 X 아이콘이 나타납니다.
아이콘에 마우스를 올리거나 클릭하면 툴팁에 상세 오류 메시지가 표시됩니다.

Web App 은 사용자 PC 환경(로컬 DB · 사내망 · 사용자 PC 의 키 파일) 에는 접근할 수 없기 때문에, 이로 인한 오류가 발생합니다.

케이스	오류 메시지 예시	해결
로컬 DB 차단 (SQLite · H2 Embedded · localhost)	`이 커넥션(SQLite/H2 Embedded/localhost 등)은 Desktop 에서만 사용 가능합니다.`	localhost DB 는 클라우드 서버에서 접근할 수 없습니다. Desktop 앱을 사용하거나, 외부에서 접근 가능한 호스트의 DB 로 변경하세요.
사내망 · 방화벽 안쪽 DB 도달 불가	`Connection refused` · `connect timed out` (호스트 / 포트 / 인증 정보는 정확한데도 발생하는 경우)	Web App 의 embedded-server 는 사내망 안쪽 DB 에는 직접 접속할 수 없습니다. 다음 중 하나로 해결하세요: • Desktop 앱 사용 (사용자 PC 에서 직접 접속) • DB 의 보안그룹 / 방화벽이 NeoSQL 서버 IP 를 허용하도록 설정 (관리자 협의) • 점프 호스트를 통한 SSH 터널 — 단, 키 파일은 Desktop 에서만 사용 가능
SSH 터널 키 파일 사용 불가	`SSH private key file not found: <path>` 또는 SSH 터널 설정이 적용되지 않음	Web App 은 사용자 PC 의 SSH 키 파일에 접근할 수 없어 SSH 터널 기능을 지원하지 않습니다. SSH 터널이 필요한 DB 는 Desktop 앱에서 사용하세요.

케이스	오류 메시지 예시	해결
Custom JDBC 드라이버 미설치	`커스텀 드라이버 "<label>"이 로컬에 없습니다. Driver Manager에서 드라이버를 설치해 주세요.` 또는 `No suitable driver found for jdbc:<scheme>:...`	NeoSQL 에 기본 번들되지 않은 드라이버를 사용하려면 직접 등록해야 합니다. 커넥션 설정 모달의 JDBC Driver Manager 에서 해당 jar 파일을 업로드하세요. (Web App 에서는 등록 불가 — Desktop 전용)
SSH 개인키 파일 경로 · 형식 오류	`SSH private key file not found: <path>` `SSH private key not configured`	SSL/SSH 탭의 SSH Tunnel 설정에서 개인 키 파일을 다시 업로드하세요. PuTTY `.ppk` 는 지원되지 않으므로 OpenSSH 형식 변환 후 사용하세요.
(Offline) 라이센스에 등록되지 않은 DB 접근	별도 오류 메시지 없음. 다음 두 가지 형태로 차단됩니다: • 프로젝트 카드에 회색 비활성화 배지 + 클릭 시 진입 차단 • 커넥션 설정 모달의 URL 입력칸이 select 박스로 전환되어 라이센스에 등록된 JDBC URL 만 선택 가능	Offline 라이센스는 발급 시 입력한 JDBC URL 목록 안에서만 동작합니다. 다른 호스트의 DB 를 사용하려면 마이페이지(웹) 에서 라이센스를 재발급받아 JDBC URL 을 추가해야 합니다. 자가발급은 TEAM 플랜에서 지원됩니다.