참고

문제 해결

NeoSQL 을 사용하다 흔히 만나는 문제를 증상, 원인, 할 일 순서로 모았습니다. 화면에 표시된 안내 문구로 찾고, 원인을 이해하려면 링크한 페이지를 읽으세요. 여기서 해결되지 않으면 버그 신고 패널로 알려 주세요.

먼저 오류 문구를 확인합니다

어디서오류를 보는 곳
커넥션 창의 연결 테스트연결 테스트 버튼 옆의 빨간 아이콘입니다. 오류가 닫힌 뒤에는 아이콘을 클릭하면 DB 가 돌려준 오류가 다시 보입니다(커넥션 만들기와 수정).
SQL 실행결과 영역에 오류와 SQLSTATE 가 보입니다(SQL 편집기).
내보내기, 백업처럼 뒤에서 처리 중인 작업상태바의 백그라운드 작업 창에서 실패한 작업의 오류를 복사하거나 다시 합니다(앱 메뉴, 상단 바와 상태바).
어디서 났는지 모르는 오류헤더의 버그 신고 버튼을 클릭하면 앱을 실행한 뒤 생긴 최근 오류가 오류 로그에 모여 있습니다.

DB 가 돌려준 오류는 번역하지 않고 그대로 보여 줍니다. 아래 표의 영문 오류는 원문의 예입니다.

DB 접속이 되지 않을 때

증상원인할 일
웹 앱에서 Desktop 전용 커넥션 안내가 표시됩니다SQLite, H2 Embedded, localhost 커넥션입니다. 웹 앱의 DB 접속은 NeoSQL 서버가 하므로 기기의 파일과 localhost 에 접속할 수 없습니다데스크톱 앱을 사용하세요. 웹 앱에서 사용하려면 인터넷에서 접속할 수 있는 호스트의 DB 로 커넥션을 만드세요(웹과 데스크톱)
웹 앱에서 Database에 연결할 수 없습니다 창이 표시됩니다NeoSQL 서버가 DB 에 접속하지 못했습니다. 사내망, VPN 안의 DB 이거나, DB 의 방화벽이 NeoSQL 서버에서 오는 접속을 차단하고 있습니다사내망 DB 는 데스크톱 앱으로 접속하세요. 인터넷에 열린 DB 라면 주소와 DNS, 방화벽을 확인하세요. 인터넷에서 접속할 수 있는 SSH 서버가 있으면 SSH 터널로 접속할 수 있습니다
데스크톱 앱에서 DB 접속 불가 알림이 표시됩니다기기에서 DB 에 접속하지 못했습니다. 주소, 포트가 틀렸거나, DB 가 비활성화되어 있거나, VPN 이 끊겼거나, 방화벽이 차단하고 있습니다호스트와 포트, DB 가 실행 중인지, VPN 에 연결됐는지 확인하세요. 같은 기기의 다른 도구로도 접속되지 않으면 네트워크 관리자에게 방화벽을 문의하세요
Connection refused, connect timed out, Communications link failure, Unknown host위와 같은 네트워크 문제입니다. 시간 초과는 방화벽이 응답 없이 차단할 때 흔히 납니다위와 같습니다. 접속 시간 제한은 커넥션 창의 속성 탭에 DBMS 의 기본 속성으로 들어 있습니다
Access denied, password authentication failed, Login failedDB 에는 접속했지만 사용자나 비밀번호가 틀렸거나, 사용자에게 기기(또는 NeoSQL 서버)에서 접속할 권한이 없습니다사용자와 비밀번호를 다시 넣으세요. MySQL, MariaDB 는 사용자마다 접속을 허용하는 호스트가 정해져 있으니 DB 관리자에게 확인하세요
MySQL, MariaDB 에서 Public Key Retrieval is not allowedcaching_sha2_password 인증에서 서버 공개키를 받지 못했습니다SSL/SSH 탭의 공개키 조회 허용 항목을 활성화하거나 SSL 을 활성화하세요(SSL/TLS 와 SSH 터널)
커넥션 창에 커스텀 드라이버 "…"이 로컬에 없습니다. Driver Manager에서 드라이버를 설치해 주세요. 표시가 보이거나 No suitable driver found커넥션이 사용하는 사용자 지정 드라이버가 기기에 없습니다. 다른 기기에서 만든 커넥션일 때 흔합니다데스크톱 앱은 프로젝트를 열 때 누락된 드라이버 설치 창으로 JAR 를 업로드하거나 번들된 기본 드라이버의 JAR로 대체 항목으로 기본 드라이버를 사용합니다. 웹 앱은 기본 드라이버만 사용합니다(드라이버 관리)
사용자 지정 드라이버를 더했는데 연결 테스트가 실패합니다드라이버 클래스 이름이 틀렸거나 DB 버전과 맞지 않는 드라이버입니다드라이버의 클래스 이름과 버전을 확인하세요(드라이버 관리)
연결은 되는데 탐색기에 스키마가 보이지 않습니다커넥션 창의 스키마 탭에서 선택한 스키마만 보입니다스키마 탭에서 스키마를 선택하고 저장하세요. 새로 만든 스키마는 스키마 목록 새로고침 버튼으로 목록을 다시 받습니다

SSL 과 SSH 터널

증상원인할 일
인증서의 이름이 접속 주소와 다르다는 오류IP 주소, 별칭, SSH 터널로 접속해 인증서의 호스트 이름과 접속 주소가 다릅니다. 서버가 정상이어도 납니다Verify CA 모드로 변경하면 인증서 확인은 유지하고 호스트 이름 확인만 건너뜁니다
서버 인증서를 신뢰할 수 없다는 오류(PKIX path building failed 등)서버 인증서를 발급한 CA 를 NeoSQL 이 모릅니다. 자체 서명 인증서일 때 흔합니다SSL/SSH 탭에 서버의 CA 인증서를 넣으세요
인증서 유효기간 오류서버 인증서가 만료됐거나, 기기의 시각이 틀립니다DB 관리자에게 인증서 갱신을 확인하고 기기의 시각을 맞추세요
TLS handshake 실패서버가 SSL 을 지원하지 않거나 프로토콜, 암호군이 맞지 않습니다서버가 SSL 을 활성화했는지 확인하고, 모르면 DB 관리자에게 지원하는 TLS 버전을 문의하세요
SSH private key not configuredSSH 인증을 Public Key 방식으로 선택했는데 개인 키가 없습니다Private Key 줄에 개인 키를 넣으세요
SSH private key file not found커넥션이 기기에 없는 키 파일 경로를 가리킵니다개인 키를 다시 업로드하세요. 업로드한 키의 내용은 커넥션에 담기므로 다른 기기와 웹 앱에서도 사용합니다
웹 앱에서 SSH 터널이 연결되지 않습니다웹 앱은 NeoSQL 서버가 SSH 서버에 접속합니다. SSH 서버가 인터넷에서 접속할 수 없습니다SSH 서버가 사내망에만 있으면 데스크톱 앱을 사용하세요

SSL 모드마다 무엇을 확인하는지는 연결과 실행 대상 의 '보안 연결' 에서 설명합니다.

회사 네트워크에서 인증서 안내가 표시될 때

데스크톱 앱에서 보안 인증서를 신뢰할 수 없습니다 창이 표시되면, 회사 방화벽, 백신, VPN 의 SSL 검사가 인증서를 변경해 끼워 앱의 로컬 서버가 NeoSQL 서버를 믿지 못한 것입니다. 브라우저는 운영체제의 인증서를 사용하므로 멀쩡해 보여도 앱만 실패합니다.

  1. 네트워크 관리자에게 회사의 루트 인증서 파일(.pem, .crt, .cer)을 받습니다.
  2. 창의 인증서 폴더 표시에 나온 폴더에 파일을 넣습니다. 폴더는 앱을 업데이트해도 삭제되지 않습니다.
  3. 앱을 완전히 종료하고 다시 실행합니다.

데스크톱 앱의 로컬 서버가 표시되지 않을 때

데스크톱 앱은 실행될 때 DB 접속을 맡는 로컬 서버를 기기에서 함께 띄웁니다. 로컬 서버는 앱에 들어 있는 Java 실행 환경에서 실행되고, 52080 번 포트부터(NeoSQLEnterprise 는 52180 번부터) 비어 있는 포트를 찾아 사용합니다(설치와 업데이트).

증상원인할 일
앱을 실행하자마자 Java 실행 환경을 찾지 못했다는 오류 창이 표시되고 앱이 닫힙니다설치 파일이 손상됐거나 백신이 앱 안의 파일을 삭제했습니다홈페이지에서 설치 파일을 다시 받아 설치하세요. 다시 설치해도 로컬 프로젝트와 설정은 보존됩니다
앱을 실행하자마자 서버 포트를 찾지 못했다는 오류 창이 표시되고 앱이 닫힙니다사용할 수 있는 포트가 없습니다기기를 다시 시작한 뒤 앱을 실행하세요
앱은 열리지만 DB 와 관련된 기능이 모두 실패합니다로컬 서버가 시작되지 못했거나 도중에 멈췄습니다앱을 완전히 종료하고 다시 실행하세요. 앱은 실행될 때 지난번에 남은 로컬 서버를 정리하고 새로 띄웁니다. 계속되면 버그 신고 로 알려 주세요

계정 프로젝트를 열거나 동기화할 때

증상원인할 일
프로젝트 데이터를 불러오는 중... 화면이 오래 갑니다처음 여는 기기이거나 문서가 많아 서버에서 받을 것이 많습니다. 받은 문서 수가 함께 보입니다기다리세요. 몇 초 지나면 취소하고 대시보드로 버튼이 나타나 홈으로 돌아갈 수 있습니다. 삭제한 기록이 많이 쌓인 프로젝트는 소유자가 프로젝트 설정 에서 동기화 데이터를 정리하면 빨라집니다
프로젝트 데이터를 동기화하지 못했습니다. 네트워크 연결을 확인해주세요. 화면이 표시됩니다프로젝트를 열 때 서버와 동기화하지 못했습니다인터넷 연결을 확인하고 다시 시도 버튼을 클릭하세요
프로젝트 정보를 불러오지 못했습니다. 다시 시도하시겠습니까? 안내가 표시됩니다프로젝트 정보를 서버에서 읽지 못했습니다다시 시도 버튼을 클릭하세요
로컬 데이터베이스 연결이 끊어졌습니다. 앱이 열려 있는 상태에서 브라우저·사이트 데이터를 삭제하면 발생할 수 있습니다. 새로고침하면 다시 연결됩니다. 안내가 표시됩니다앱이 열린 채로 브라우저나 사이트의 데이터를 삭제해 기기 안의 저장소 연결이 끊겼습니다새로고침 버튼을 클릭하세요
프로젝트 다시 불러오기 창이 표시됩니다프로젝트를 보지 않는 동안 서버의 동기화 이력이 정리됐습니다다시 불러오세요. 나중으로 미루면 그동안의 변경은 기기에만 남습니다
헤더 아래에 서버와 통신할 수 없어 플랜과 계정 프로젝트를 불러오지 못했습니다. 안내 줄이 생깁니다로그인한 상태에서 NeoSQL 서버와 통신하지 못했습니다다시 시도 버튼을 클릭하세요. 로컬 프로젝트는 그동안에도 사용할 수 있습니다(앱 메뉴, 상단 바와 상태바)
ERD 동기화 충돌 창이나 SQL 동기화 충돌 창이 표시됩니다다른 기기나 팀원이 같은 문서를 먼저 저장했습니다내 것을 저장할지 서버의 것으로 변경할지 선택합니다(협업과 권한)
팀 ERD 로 변경한 뒤 ERD는 팀에 공유됐지만 로컬 동기화가 지연되고 있습니다. 프로젝트를 다시 열어 주세요. 안내가 표시됩니다서버에는 팀 ERD 가 됐지만 기기의 동기화가 늦습니다프로젝트를 닫았다가 다시 여세요

프로젝트에 들어갈 수 없을 때

증상원인할 일
프로젝트 정리 중 안내가 표시됩니다프로젝트의 플랜이 낮아져 소유자가 남길 멤버를 선택하기 전입니다소유자가 프로젝트에 들어가 정리를 마칠 때까지 기다리세요(플랜과 기능 차이)
이 프로젝트의 공유 인원이 가득 차 진입할 수 없습니다. 프로젝트 소유자에게 문의하세요. 안내가 표시됩니다플랜 정리로 프로젝트에서 비활성화됐습니다프로젝트 소유자에게 다시 활성화해 달라고 요청하세요
홈에서 프로젝트를 클릭하면 관리 전용 프로젝트 안내가 표시됩니다워크스페이스 멤버가 만든 프로젝트입니다. 워크스페이스 소유자는 관리만 합니다함께 사용하려면 프로젝트를 만든 멤버에게 초대해 달라고 하세요(워크스페이스)
웹 앱이나 다른 기기에서 로컬 프로젝트가 보이지 않습니다로컬 프로젝트는 만든 기기에만 저장됩니다만든 기기의 데스크톱 앱에서 여세요. 여러 기기에서 사용할 프로젝트는 계정 프로젝트로 만드세요
로그아웃했더니 프로젝트가 사라졌습니다로그아웃하면 계정 프로젝트가 홈에서 빠집니다. 삭제된 것은 아닙니다같은 계정으로 다시 로그인하세요(로그인과 프로젝트 종류)

로그인할 때

증상원인할 일
데스크톱 앱에서 브라우저로 로그인 버튼을 클릭했는데 브라우저 탭이 보이지 않습니다브라우저가 다른 창 뒤에 열렸거나 열리지 않았습니다기다리는 화면의 돌아가서 다시 시도하기 링크를 클릭하고 다시 시도하세요
브라우저에서 로그인했는데 앱으로 돌아오지 않습니다브라우저가 NeoSQL 앱을 열지 묻는 창에서 허용하지 않았습니다브라우저의 확인 창에서 앱 열기를 허용하세요(처음 실행하기)
이메일 인증을 기다리는 중입니다 화면이 표시됩니다가입한 이메일을 아직 인증하지 않았습니다메일함과 스팸함에서 인증 메일을 찾아 링크를 클릭하고, 없으면 인증 메일 다시 보내기 버튼을 클릭하세요(가입과 로그인)
사용하던 중 로그인이 만료되었습니다. 다시 로그인해 주세요. 알림이 표시됩니다로그인이 만료됐습니다다시 로그인하세요. 데스크톱 앱에서 로컬 프로젝트를 보고 있었으면 로그인하지 않고 그대로 이어서 사용합니다
비밀번호를 잊었습니다가입한 이메일로 재설정합니다비밀번호 에서 재설정하는 방법을 설명합니다

업데이트할 때

증상원인할 일
업데이트 확인 실패 알림이 표시됩니다NeoSQL 서버에 접속하지 못했습니다인터넷 연결을 확인하고 잠시 뒤 다시 확인하세요
배포본을 아직 찾지 못했습니다 알림이 표시됩니다새 버전은 나왔지만 받을 파일이 아직 올라오지 않았습니다잠시 뒤 다시 확인하세요
헤더에 업데이트 오류 표시가 남습니다업데이트 파일을 다운로드하거나 설치하지 못했습니다. 회사 네트워크가 GitHub 의 파일 다운로드하기를 차단하는 경우가 많습니다홈페이지에서 새 설치 파일을 다운로드해 설치하세요. 프로젝트와 설정은 보존됩니다(설치와 업데이트)
웹 앱에 새 버전이 배포되었습니다 안내가 표시됩니다새 버전이 배포됐습니다작성 중인 내용을 저장하고 새로고침 버튼을 클릭하세요
Windows 에서 SmartScreen 경고, macOS 에서 열지 묻는 창이 표시됩니다인터넷에서 받은 앱을 처음 열 때의 확인입니다설치와 업데이트 에서 게시자를 확인하는 방법을 설명합니다

내보내기와 백업이 실패할 때

증상원인할 일
웹 앱에서 내보내기나 백업 메뉴를 클릭하면 해당 기능은 앱에서만 사용할 수 있습니다. 안내가 표시됩니다탐색기 우클릭데이터 내보내기... 메뉴, 탐색기 우클릭데이터 가져오기... 메뉴, 탐색기 우클릭Native Backup... 메뉴, 탐색기 우클릭Native Reload... 메뉴는 로컬 서버가 기기에 파일을 기록하고 읽는 기능입니다데스크톱 앱을 사용하세요(웹과 데스크톱)
Excel 내보내기가 실패합니다셀 한 칸의 한도(32,767자)를 넘는 값이 있고, 긴 텍스트 처리 (32,767자 초과 셀) 항목이 실패 처리로 되어 있습니다같은 항목에서 분할이나 잘라서 기록하는 방식을 선택하거나 CSV, JSON 으로 내보내세요(결과 내보내기)
파일 이름 끝에 _lossy 가 붙었습니다형식의 한계로 원래 값을 그대로 기록하지 못한 값이 있습니다. 파일로는 원래 데이터를 되살릴 수 없습니다결과 내보내기 에서 손실이 생기는 경우를 확인하세요
웹 앱에서 결과가 상한까지만 옵니다웹 앱은 플랜에 따라 SQL 결과와 내보내기의 행 수에 상한이 있습니다데스크톱 앱을 사용하거나 플랜을 확인하세요(플랜과 기능 차이)
Native Backup 이 실패합니다DBMS 의 덤프 도구(pg_dump, mysqldump 등)가 기기에 없거나 다른 실행 파일을 선택했습니다덤프 도구를 설치하고 로컬 클라이언트 칸에서 실행 파일을 선택하세요. 선택하면 실행해 보고 버전을 보여 줍니다(데이터 내보내기, 가져오기와 Native Backup)
PostgreSQL 백업 파일을 복원하지 못합니다덤프 도구와 서버의 메이저 버전이 다릅니다서버와 같은 메이저 버전의 도구로 다시 백업하세요
ERD 이미지에 워터마크가 붙습니다로그인하지 않았거나 플랜이 워터마크를 붙입니다이미지 내보내기 에서 워터마크 규칙을 확인하세요

MCP 가 연결되지 않을 때

외부 AI 가 NeoSQL 도구를 호출하지 못하면 클라이언트가 보여 주는 도구 결과를 확인하세요. 대부분의 실패한 결과에는 status 값과 영어 안내가 들어 있습니다. 설치하는 방법은 MCP 설치와 연결 에서 설명합니다.

증상원인할 일
클라이언트의 MCP 서버 목록에 neosql 이 없거나 실패로 보입니다설정을 넣은 뒤 클라이언트를 다시 시작하지 않았거나, 클라이언트가 npx 를 찾지 못했거나, Node.js 가 20 보다 낮습니다클라이언트를 다시 시작하세요. 터미널에서 node --version 으로 Node.js 의 버전을 확인하세요. 터미널에서는 되는데 클라이언트에서 안 되면, 클라이언트가 보는 PATH 에 Node.js 가 있는지 확인하세요
Claude Code 에 NeoSQL 도구가 두 벌 보입니다앱에서 등록하거나 직접 넣은 설정과 플러그인이 함께 있습니다Claude Code 의 /mcp 에서 하나를 종료하세요
installation_not_foundMCP 서버가 데스크톱 앱의 설치를 찾지 못했습니다. macOS 는 응용 프로그램 폴더(/Applications, ~/Applications)와, 앱이 실행될 때마다 남기는 앱의 위치를 봅니다. Windows 는 설치 파일로 설치한 앱을 찾습니다데스크톱 앱을 설치하세요. 이미 설치했다면 앱을 직접 실행한 뒤 다시 요청하세요. macOS 는 앱을 한 번 실행하면 다음부터 앱을 찾습니다
NeoSQLEnterprise 를 사용하는데 외부 AI 가 NeoSQL 앱을 실행하거나 installation_not_found 가 표시됩니다설정이 NeoSQLEnterprise 앱에서 만든 것이 아닙니다. Claude 플러그인과 npx 로 실행하는 설정은 NeoSQL 앱에 연결합니다NeoSQLEnterprise 앱에서 다시 등록하세요(MCP 설치와 연결)
NeoSQLEnterprise 를 옮기거나 다시 설치한 뒤 클라이언트가 neosql MCP 서버를 시작하지 못합니다설정에 적힌 앱 실행 파일이나 MCP 서버 파일의 경로가 바뀌었습니다NeoSQLEnterprise 앱에서 다시 등록하세요
activation_failed, installation_check_failed, status_check_failedMCP 서버가 데스크톱 앱을 띄우지 못했거나, 앱의 설치나 상태를 확인하지 못했습니다앱을 직접 실행하고, 프로젝트가 열린 뒤 다시 요청하세요
readiness_timeout40초 안에 앱이나 프로젝트가 준비되지 않았습니다. 요청은 앱에 보내지 않았습니다앱에 로딩 오류나 확인할 안내가 표시되어 있는지 보고, 프로젝트가 열린 뒤 다시 요청하세요. 앱이 응답하지 않으면 앱을 다시 시작하세요
app_not_ready앱은 실행되어 있지만 화면이나 프로젝트가 아직 다 열리지 않았습니다앱이 다 열린 뒤 다시 요청하세요
project_not_selected데스크톱 앱에 열린 프로젝트가 없습니다앱에서 프로젝트를 열거나, 외부 AI 에게 프로젝트 목록을 보고 선택하라고 요청하세요
authentication_required, unauthenticated계정 프로젝트를 대상으로 했는데 데스크톱 앱에 로그인하지 않았습니다앱에서 로그인하세요. 로그인하지 않으면 로컬 프로젝트만 다룹니다
user_action_required프로젝트를 열기 전에 앱에서 처리할 것이 있습니다. 예를 들어 저장하지 않은 변경, ZK 암호화를 활성화한 프로젝트의 잠금해제, 커넥션이나 멤버의 플랜 정리, 기기에 없는 사용자 지정 드라이버, 확인할 안내가 있습니다앱 화면에서 처리한 뒤 다시 요청하세요
project_load_failed프로젝트를 불러오지 못했습니다앱에 표시된 오류를 해결한 뒤 다시 요청하세요
target_unavailable, project_lookup_failed, project_navigation_failed, project_mismatch대상 프로젝트(외부 AI 가 선택한 프로젝트나 설정의 --project-id)를 열지 못했거나, 요청하는 동안 앱의 프로젝트가 변경되었습니다. 다른 프로젝트에서 실행하지 않고 멈춥니다프로젝트 ID 와 접근 권한을 확인하고, 앱에서 대상 프로젝트로 돌아간 뒤 다시 요청하세요
project_conflict설정의 --project-id 로 프로젝트를 고정했는데, 외부 AI 가 다른 프로젝트를 대상으로 하거나 새 프로젝트를 만들려고 했습니다. 요청은 보내지 않았습니다고정한 프로젝트에서 작업하세요. 다른 프로젝트도 다루려면 클라이언트 설정에서 --project-id 를 삭제하세요
unresponsive앱에 보낸 요청이 제한 시간 안에 끝나지 않았습니다. 요청은 한 번 보냈고 다시 보내지 않습니다DB 나 파일이 이미 변경되었을 수 있습니다. 결과를 확인한 뒤 다시 요청하세요

그래도 해결되지 않으면

  • 앱 안에서 버그 신고 패널로 보내 주세요. 앱 버전, OS, 보던 화면, 최근 오류가 자동으로 포함됩니다.
  • 앱을 사용할 수 없는 상황이거나 문제가 아닌 문의는 문의하기 의 방법으로 보내 주세요.

관련 화면