문제 해결
증상을 찾고, 원인을 읽고, 해결 방법을 적용하세요. 여기에 없는 문제라면 무엇을 했고 무엇이 일어났는지 자세히 적어 issue를 열어 주세요.
설치와 실행
| 증상 | 원인과 해결 |
|---|---|
| Intel Mac에서 앱이 열리지 않음 | macOS 릴리스는 Apple silicon 전용으로 빌드되었습니다. Intel에서는 소스에서 빌드하세요 |
| 이 문서의 바로 가기가 Windows나 Linux에서 동작하지 않음 | **⌘**를 Ctrl로 바꿔 읽으세요. 여기서 ⌘↵는 Ctrl+Enter입니다 |
ducklocal: command not found | 디스크 이미지는 앱을 설치할 뿐 명령은 설치하지 않습니다. 바이너리를 PATH에 링크하세요 |
| 창이 열려 있는 동안 터미널이 사용 중임 | 터미널에서 GUI를 실행하면 포그라운드에서 동작합니다. 대신 응용 프로그램에서 실행하거나, 그 터미널을 그대로 두세요 |
| 기록, 설정, 기억된 파일이 더 이상 저장되지 않음 | 두 번째 DuckLocal이 실행 중이며 앱 데이터 파일을 잡고 있습니다. 다른 하나를 종료하고 다시 실행하세요 |
| 지난번 DuckLocal이 예기치 않게 종료되었습니다 | 크래시가 발생해 로그 폴더에 보고서를 저장했습니다. 보고서 표시를 클릭해 issue에 첨부하세요 — 저장 위치를 참고하세요 |
| 업데이트 확인 실패 | 마우스를 올리면 이유가 나옵니다: 오프라인, 프록시, 또는 체크섬이 일치하지 않은 다운로드입니다. 클릭해 다시 시도하거나 GitHub에서 릴리스를 내려받으세요 — 업데이트 확인 참고 |
데이터 열기
| 증상 | 원인과 해결 |
|---|---|
지정한 경로에서 File not found | 경로가 없거나, 생각하는 것과 다른 디렉터리 기준의 상대 경로입니다. 확실히 하려면 절대 경로를 사용하세요 |
| 폴더에 데이터 파일이 없다고 나옴 | 그 아래에 .csv, .tsv, .txt, .parquet, .json, .ndjson, .jsonl, .xlsx, .xls, .xlsb, .ods 중 어느 것도 맞지 않았습니다 |
| 폴더에서 예상보다 적은 파일이 나옴 | 숨은 항목과 심볼릭 링크는 건너뛰고, 한 번의 열기 요청은 최대 256개 파일을 연결합니다. 하위 폴더를 따로 여세요 |
| 경로가 예기치 않게 데이터베이스로 열림 | 데이터 파일이 아닌 기존 파일은 DuckDB 데이터베이스로 취급됩니다. 열리지 않으면 DuckLocal이 이유를 알려 주고, 실행 시에는 메모리로 대체됩니다. 데이터베이스 열기를 참고하세요 |
| 연결되지 않았습니다 …: 데이터베이스에 이미 … 이름의 테이블 또는 뷰가 있습니다 | 데이터베이스에 기억된 파일과 같은 이름의 테이블이나 뷰가 이미 있습니다. DuckLocal은 그것을 절대 바꾸지 않습니다. 둘 중 하나의 이름을 바꾸거나 삭제하거나, 로컬 파일에서 그 파일을 제거하고 다시 열어 새 이름을 받으세요 |
| 상대 경로를 복원할 수 없습니다 … | 파일이 상대 경로로 기억되어 새 세션에서는 해석할 수 없습니다. 로컬 파일에서 제거하고 다시 여세요 |
뷰가 sales 대신 sales_2로 표시됨 | 다른 파일이나 테이블이 이미 그 이름을 쓰고 있어 새 뷰에 접미사가 붙었습니다 |
| 파일의 뷰가 오래된 내용을 보여 줌 | 뷰는 쿼리할 때마다 파일을 읽습니다. CSV의 열 구성이 바뀌었다면 사이드바의 스키마 새로 고침을 사용하세요 |
데이터베이스 열기
| 증상 | 원인과 해결 |
|---|---|
| 데이터베이스가 더 새로운 DuckDB에서 만들어졌다는 메시지 | 파일이 DuckLocal에 내장된 DuckDB가 읽을 수 있는 것보다 새로운 저장 형식을 사용합니다. 그 파일을 만든 DuckDB에서 메시지에 있는 ATTACH … COPY FROM DATABASE 줄을 실행한 뒤 복사본을 여세요. 데이터베이스가 열리지 않을 때를 참고하세요 |
| 데이터베이스가 DuckDB v0.9 이전에서 왔다는 메시지 | 그 파일을 기록한 DuckDB에서 EXPORT DATABASE 'dir'를 실행한 다음 DuckLocal에서 IMPORT DATABASE 'dir'을 실행하세요 |
| SQLite 데이터베이스라는 메시지 | 열지 말고 **열기 → 데이터베이스 연결…**로 연결하세요 |
| 파일이 DuckDB 데이터베이스가 아니라는 메시지 | 확장자가 DuckLocal이 데이터로 읽는 것이 아니어서 데이터베이스로 시도되었습니다. 지원되는 확장자를 붙이거나, 예를 들어 SELECT * FROM read_csv('export.dat')처럼 SQL로 읽으세요 |
| DuckDB가 파일에 잠금을 설정할 수 없다고 함 | 다른 프로그램 — 다른 DuckDB, 스크립트, 두 번째 앱 — 이 그 데이터베이스를 쓰기용으로 열고 있으며, DuckDB는 한 프로세스만 파일에 쓸 수 있습니다. 그쪽에서 닫은 다음 파일을 다시 여세요 |
| DuckDB가 권한이 거부되었다고 함 | 계정이 파일을 읽을 수 없거나 쓸 수 없습니다. 기본 데이터베이스는 쓰기용으로 열립니다. 파일 권한을 고치거나, 읽기 전용을 선택한 상태로 연결하세요 |
| 데이터베이스 열기가 실패했는데 아무것도 바뀌지 않음 | DuckLocal이 실행 중일 때는 정상입니다. 열기에 실패하면 이전 워크스페이스가 그대로 남습니다. 알림에서 이유를 확인하세요 |
| 상태 표시줄 툴팁에 **readable by DuckDB v1.x+**가 나오고 동료가 파일을 열 수 없음 | 동료의 DuckDB가 그 버전보다 오래되었습니다. 동료가 업그레이드하거나, 더 오래된 STORAGE_VERSION으로 파일을 복사해야 합니다 — 어떤 DuckDB가 데이터베이스를 읽을 수 있는지를 참고하세요 |
연결된 데이터베이스
| 증상 | 원인과 해결 |
|---|---|
| 다시 실행한 뒤 연결된 데이터베이스가 사라짐 | 실행 시점에 기억된 경로에 파일이 없어 건너뛰었습니다. 등록은 유지되므로 파일을 되돌려 놓으면 다음 연결 때 다시 나타납니다 |
| 이 데이터베이스는 이미 …(으)로 열려 있습니다 | 그 파일이 이미 기본 데이터베이스이거나 그 이름으로 연결되어 있습니다. 그 이름으로 쿼리하세요 |
| 연결할 수 없습니다 …: … 이름은 열린 데이터베이스에서 이미 사용 중입니다. | 연결 안의 다른 무언가가 기억된 별칭을 이미 사용하고 있습니다. 예를 들어 SQL에서 같은 이름으로 연결한 데이터베이스입니다. 그것을 DETACH한 다음 데이터베이스를 다시 열거나 다시 실행하세요 |
| 연결된 데이터베이스에 쓰기가 실패함 | 기본값인 읽기 전용으로 연결되었습니다. 사이드바에서 데이터베이스 연결 해제를 한 다음 읽기 전용을 선택 해제하고 다시 연결하세요 |
| 연결했더니 빈 데이터베이스가 만들어짐 | 읽기 전용을 선택 해제한 상태에서는 존재하지 않는 DuckDB 경로가 생성됩니다. 연결을 해제하고 빈 파일을 삭제한 뒤 경로를 확인하세요 |
| 데이터베이스를 지정하지 않은 테이블 이름이 엉뚱한 테이블을 찾음 | 데이터베이스 없이 쓴 이름은 기본 데이터베이스에서 해석됩니다. 데이터베이스를 오른쪽 클릭해 기본 데이터베이스로 사용을 선택하거나 alias.table처럼 쓰세요 |
Finder와 Quick Look
macOS에서만 해당됩니다.
| 증상 | 원인과 해결 |
|---|---|
.parquet 또는 .duckdb 파일을 더블 클릭하면 다른 앱이 열림 | 그 앱이 이미 기본값입니다. Finder에서 정보 가져오기 → 다음으로 열기로 DuckLocal을 선택한 다음 **모두 변경…**을 클릭하세요 |
| CSV 또는 Excel 파일을 더블 클릭해도 DuckLocal이 열리지 않음 | 의도된 동작입니다. DuckLocal은 이 형식을 가져오지 않습니다. 다음으로 열기 → DuckLocal을 사용하거나 파일을 Dock 아이콘에 놓으세요 |
| 다음으로 열기에 DuckLocal이 없거나 Space를 눌러도 DuckLocal 미리보기가 나오지 않음 | macOS가 아직 앱을 등록하지 않았습니다. 앱을 응용 프로그램으로 옮기고 한 번 실행하세요. 미리보기는 그다음 터미널에서 qlmanage -r을 실행하고, 시스템 설정의 확장 기능 설정에서 Quick Look 아래 DuckLocal Preview가 켜져 있는지 확인하세요 |
일반 .json 또는 Excel 파일에 DuckLocal 미리보기가 나오지 않음 | 의도된 동작입니다. 그 형식은 macOS 자체 미리보기에 맡깁니다. .jsonl과 .ndjson 파일은 미리보기가 됩니다 |
| 미리보기에 50행만 나옴 | 의도된 동작입니다. 미리보기는 파일 전체를 스캔하지 않습니다. 나머지는 DuckLocal에서 파일을 여세요 |
.duckdb 파일의 미리보기에 오류가 나옴 | 미리보기는 DuckLocal 자체의 DuckDB로 파일을 읽으므로, 더 새로운 DuckDB의 파일은 거기서도 실패합니다. 데이터베이스 열기를 참고하세요 |
쿼리 실행
| 증상 | 원인과 해결 |
|---|---|
| 실행을 눌러도 아무 일도 없음 | 이미 쿼리가 실행 중입니다. 실행 옆의 중지를 누르거나 **⌘.**로 중단하세요 |
쿼리가 Interrupted로 실패함 | 실행 중에 누군가 중지(또는 ⌘.)를 눌렀습니다. 다시 실행하세요 |
| SQL 일부에 빨간 물결 밑줄이 있음 | 마지막 실행이 그 지점에서 실패했습니다. 쿼리 실패 메시지를 읽으세요. 표시는 다음 실행 때 사라집니다 |
| **⌘↵**를 눌렀는데 실행되지 않고 에디터가 나옴 | 첫 실행 화면에서 ⌘↵는 "에디터를 달라"는 뜻입니다. 한 번 더 누르면 실행됩니다 |
| 결과가 잘림 알림과 함께 일찍 끝남 | 100,000행 또는 2,000,000셀 한도에 도달했습니다. 쿼리 범위를 좁히세요. 페이지 이동은 없습니다 |
| 타임스탬프가 밀려 보임 | 그리드는 타임스탬프를 로컬 시간이 아니라 UTC로 표시합니다 |
TIMETZ 값에서 오프셋이 사라졌거나, BIT 또는 BIGNUM 값이 바이트처럼 보임 | 그런 유형은 DuckLocal로 오는 과정에서 일반 값과 구분할 수 없습니다. SQL에서 CAST(column AS VARCHAR)로 실제 값을 확인하세요 |
| 정렬해도 미리보기 밖의 행이 나오지 않음 | 헤더 정렬은 이미 불러온 행만 재배치합니다. 잘리기 전의 전체 결과를 정렬하려면 SQL에서 ORDER BY를 사용하세요 |
| 쿼리에 설치되지 않은 확장 기능이 필요함 | 이제 빠진 확장 기능을 자동으로 내려받지 않습니다. 확장 기능 탭에서 직접 설치한 다음 로드하거나 쿼리를 다시 실행하세요 |
| 0.3.0 이전에 동작하던 쿼리가 확장 기능이 설치되지 않았다거나 함수가 없다고 함 | DuckLocal 0.3.0은 DuckDB 2.0을 실행하며, 설치된 확장 기능을 릴리스별로 관리합니다. 확장 기능 탭에서 다시 설치하세요 — 확장 기능을 참고하세요 |
minutes처럼 따옴표 없는 열 별칭이 파서 오류를 냄 | SQL 키워드이기 때문입니다. AS minutes라고 쓰거나 따옴표로 감싸세요: SELECT count(*) AS "minutes" FROM events |
| 테이블이나 기록 항목을 클릭했더니 SQL이 사라짐 | 그 클릭은 에디터 버퍼 전체를 바꿉니다. 임시 작업에는 새 쿼리 탭을 사용하세요 |
| 내보내기가 조용히 파일을 바꿔 버림 | 내보내기는 묻지 않고 지정한 경로에 씁니다. 새 이름을 고르세요 |
S3
| 증상 | 원인과 해결 |
|---|---|
| S3 자격 증명이 사라짐 | 설계상 세션 동안에만 유지되며, 데이터베이스를 열거나 전환하면 지워집니다. S3을 다시 설정하세요 |
| 오프라인에서 S3 설정이 실패함 | 첫 사용 시 INSTALL httpfs가 실행되며 확장 기능을 내려받습니다. 한 번 연결하면 캐시됩니다 |
| 임시(STS) 자격 증명이 거부됨 | 세션 토큰을 보내지 않습니다. 수명이 긴 키를 사용하세요 — S3와 httpfs를 참고하세요 |
| 버킷이 실제보다 작아 보임 | 목록은 단계마다 1,000개에서 멈춥니다. 대신 's3://bucket/prefix/*.parquet' 같은 글롭으로 쿼리하세요 |
대시보드
| 증상 | 원인과 해결 |
|---|---|
| 대시보드 차트가 쿼리가 읽기 전용이어야 한다고 함 | .dash 쿼리가 쓰기를 시도했습니다(DDL, DML, COPY, ATTACH 등). 대시보드는 읽기 전용 문만 실행하므로 준비 작업은 SQL 에디터로 옮기세요 |
| 에이전트가 내 주석을 보지 못함 | 주석은 어디로도 전송되지 않습니다. 에이전트가 직접 읽어야 합니다. ducklocal comments FILE을 실행하게 하거나, 공식 스킬이 있다면 "FILE의 주석을 처리해 줘"라고 요청하세요 |
| 에이전트의 답변이나 수정이 보이지 않음 | 창은 스펙과 FILE.comments.json을 1초 안에 따라갑니다. 더 이상 검증되지 않는 스펙은 마지막으로 동작한 대시보드를 그대로 두고 그 위에 이유를 표시합니다. 스펙 보기를 열어 파일을 확인하세요 |
대시보드의 PIVOT이 거부됨 | SELECT나 WITH 안에 중첩된 PIVOT은 값을 지정해야 합니다. PIVOT t ON channel IN ('Web', 'Store') USING sum(revenue)처럼 나열하거나, 쿼리를 PIVOT으로 시작하세요 |
모양
| 증상 | 원인과 해결 |
|---|---|
| 실행할 때마다 테마가 밝게 초기화됨 | 테마는 실행 사이에 저장되지 않습니다. 언어는 저장됩니다 |
| 텍스트나 아이콘이 너무 작거나 큼 | 제목 표시줄의 Aa 버튼이나 ⌘+ / ⌘− / ⌘0을 사용하세요. 인터페이스 크기를 참고하세요 |
| 인터페이스 언어가 잘못됨 | 제목 표시줄의 EN / 中 버튼을 사용하세요. 선택은 기억됩니다 |
처음부터 다시 시작
기록, 기억된 파일, 열린 탭, 설정을 지우려면 DuckLocal을 종료하고 앱 데이터 디렉터리를 삭제하세요:
bash
rm -rf ~/Library/Application\ Support/DuckLocal데이터 파일은 절대 건드리지 않습니다. DuckLocal 자체 기록만 제거됩니다. 그곳에 무엇이 저장되는지는 설정과 앱 데이터를 참고하세요.
