# 문제 해결

> DuckLocal에서 흔한 문제의 해결 방법: ducklocal 명령을 찾을 수 없음, 파일이 연결되지 않음, 데이터베이스가 열리지 않음, 멈춘 쿼리, S3와 대시보드.

Source: https://ducklocal.app/docs/ko/troubleshooting

증상을 찾고, 원인을 읽고, 해결 방법을 적용하세요. 여기에 없는 문제라면 무엇을
했고 무엇이 일어났는지 자세히 적어 [issue를 열어](https://github.com/JetSquirrel/DuckLocal/issues) 주세요.

## 설치와 실행

| 증상 | 원인과 해결 |
| --- | --- |
| Intel Mac에서 앱이 열리지 않음 | macOS 릴리스는 Apple silicon 전용으로 빌드되었습니다. Intel에서는 [소스에서 빌드](development.md#build-and-run)하세요 |
| 이 문서의 바로 가기가 Windows나 Linux에서 동작하지 않음 | **⌘**를 **Ctrl**로 바꿔 읽으세요. 여기서 ⌘↵는 Ctrl+Enter입니다 |
| `ducklocal: command not found` | 디스크 이미지는 앱을 설치할 뿐 명령은 설치하지 않습니다. [바이너리를 PATH에 링크](getting-started.md#add-command)하세요 |
| 창이 열려 있는 동안 터미널이 사용 중임 | 터미널에서 GUI를 실행하면 포그라운드에서 동작합니다. 대신 응용 프로그램에서 실행하거나, 그 터미널을 그대로 두세요 |
| 기록, 설정, 기억된 파일이 더 이상 저장되지 않음 | 두 번째 DuckLocal이 실행 중이며 앱 데이터 파일을 잡고 있습니다. 다른 하나를 종료하고 다시 실행하세요 |
| **지난번 DuckLocal이 예기치 않게 종료되었습니다** | 크래시가 발생해 로그 폴더에 보고서를 저장했습니다. **보고서 표시**를 클릭해 [issue](https://github.com/JetSquirrel/DuckLocal/issues)에 첨부하세요 — [저장 위치](settings-and-data.md#where-things-are-stored)를 참고하세요 |
| **업데이트 확인 실패** | 마우스를 올리면 이유가 나옵니다: 오프라인, 프록시, 또는 체크섬이 일치하지 않은 다운로드입니다. 클릭해 다시 시도하거나 GitHub에서 릴리스를 내려받으세요 — [업데이트 확인](settings-and-data.md#update-check) 참고 |

## 데이터 열기

| 증상 | 원인과 해결 |
| --- | --- |
| 지정한 경로에서 `File not found` | 경로가 없거나, 생각하는 것과 다른 디렉터리 기준의 상대 경로입니다. 확실히 하려면 절대 경로를 사용하세요 |
| 폴더에 데이터 파일이 없다고 나옴 | 그 아래에 `.csv`, `.tsv`, `.txt`, `.parquet`, `.json`, `.ndjson`, `.jsonl`, `.xlsx`, `.xls`, `.xlsb`, `.ods` 중 어느 것도 맞지 않았습니다 |
| 폴더에서 예상보다 적은 파일이 나옴 | 숨은 항목과 심볼릭 링크는 건너뛰고, 한 번의 열기 요청은 최대 256개 파일을 연결합니다. 하위 폴더를 따로 여세요 |
| 경로가 예기치 않게 데이터베이스로 열림 | 데이터 파일이 아닌 기존 파일은 DuckDB 데이터베이스로 취급됩니다. 열리지 않으면 DuckLocal이 이유를 알려 주고, 실행 시에는 메모리로 대체됩니다. [데이터베이스 열기](#opening-a-database)를 참고하세요 |
| **연결되지 않았습니다 …: 데이터베이스에 이미 … 이름의 테이블 또는 뷰가 있습니다** | 데이터베이스에 기억된 파일과 같은 이름의 테이블이나 뷰가 이미 있습니다. DuckLocal은 그것을 절대 바꾸지 않습니다. 둘 중 하나의 이름을 바꾸거나 삭제하거나, **로컬 파일**에서 그 파일을 제거하고 다시 열어 새 이름을 받으세요 |
| **상대 경로를 복원할 수 없습니다 …** | 파일이 상대 경로로 기억되어 새 세션에서는 해석할 수 없습니다. **로컬 파일**에서 제거하고 다시 여세요 |
| 뷰가 `sales` 대신 `sales_2`로 표시됨 | 다른 파일이나 테이블이 이미 그 이름을 쓰고 있어 새 뷰에 접미사가 붙었습니다 |
| 파일의 뷰가 오래된 내용을 보여 줌 | 뷰는 쿼리할 때마다 파일을 읽습니다. CSV의 열 구성이 바뀌었다면 사이드바의 **스키마 새로 고침**을 사용하세요 |

## 데이터베이스 열기 {#opening-a-database}

| 증상 | 원인과 해결 |
| --- | --- |
| 데이터베이스가 더 새로운 DuckDB에서 만들어졌다는 메시지 | 파일이 DuckLocal에 내장된 DuckDB가 읽을 수 있는 것보다 새로운 저장 형식을 사용합니다. 그 파일을 만든 DuckDB에서 메시지에 있는 `ATTACH … COPY FROM DATABASE` 줄을 실행한 뒤 복사본을 여세요. [데이터베이스가 열리지 않을 때](data-sources.md#when-a-database-will-not-open)를 참고하세요 |
| 데이터베이스가 DuckDB v0.9 이전에서 왔다는 메시지 | 그 파일을 기록한 DuckDB에서 `EXPORT DATABASE 'dir'`를 실행한 다음 DuckLocal에서 `IMPORT DATABASE 'dir'`을 실행하세요 |
| SQLite 데이터베이스라는 메시지 | 열지 말고 **열기 → 데이터베이스 연결…**로 연결하세요 |
| 파일이 DuckDB 데이터베이스가 아니라는 메시지 | 확장자가 DuckLocal이 데이터로 읽는 것이 아니어서 데이터베이스로 시도되었습니다. [지원되는 확장자](data-sources.md#supported-file-formats)를 붙이거나, 예를 들어 `SELECT * FROM read_csv('export.dat')`처럼 SQL로 읽으세요 |
| DuckDB가 파일에 잠금을 설정할 수 없다고 함 | 다른 프로그램 — 다른 DuckDB, 스크립트, 두 번째 앱 — 이 그 데이터베이스를 쓰기용으로 열고 있으며, DuckDB는 한 프로세스만 파일에 쓸 수 있습니다. 그쪽에서 닫은 다음 파일을 다시 여세요 |
| DuckDB가 권한이 거부되었다고 함 | 계정이 파일을 읽을 수 없거나 쓸 수 없습니다. 기본 데이터베이스는 쓰기용으로 열립니다. 파일 권한을 고치거나, **읽기 전용**을 선택한 상태로 연결하세요 |
| 데이터베이스 열기가 실패했는데 아무것도 바뀌지 않음 | DuckLocal이 실행 중일 때는 정상입니다. 열기에 실패하면 이전 워크스페이스가 그대로 남습니다. 알림에서 이유를 확인하세요 |
| 상태 표시줄 툴팁에 **readable by DuckDB v1.x+**가 나오고 동료가 파일을 열 수 없음 | 동료의 DuckDB가 그 버전보다 오래되었습니다. 동료가 업그레이드하거나, 더 오래된 `STORAGE_VERSION`으로 파일을 복사해야 합니다 — [어떤 DuckDB가 데이터베이스를 읽을 수 있는지](data-sources.md#storage-version)를 참고하세요 |

## 연결된 데이터베이스

| 증상 | 원인과 해결 |
| --- | --- |
| 다시 실행한 뒤 연결된 데이터베이스가 사라짐 | 실행 시점에 기억된 경로에 파일이 없어 건너뛰었습니다. 등록은 유지되므로 파일을 되돌려 놓으면 다음 연결 때 다시 나타납니다 |
| **이 데이터베이스는 이미 …(으)로 열려 있습니다** | 그 파일이 이미 기본 데이터베이스이거나 그 이름으로 연결되어 있습니다. 그 이름으로 쿼리하세요 |
| **연결할 수 없습니다 …: … 이름은 열린 데이터베이스에서 이미 사용 중입니다.** | 연결 안의 다른 무언가가 기억된 별칭을 이미 사용하고 있습니다. 예를 들어 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의 파일은 거기서도 실패합니다. [데이터베이스 열기](#opening-a-database)를 참고하세요 |

## 쿼리 실행

| 증상 | 원인과 해결 |
| --- | --- |
| **실행**을 눌러도 아무 일도 없음 | 이미 쿼리가 실행 중입니다. 실행 옆의 **중지**를 누르거나 **⌘.**로 중단하세요 |
| 쿼리가 `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을 실행하며, 설치된 확장 기능을 릴리스별로 관리합니다. **확장 기능** 탭에서 다시 설치하세요 — [확장 기능](schema-and-history.md#extensions)을 참고하세요 |
| `minutes`처럼 따옴표 없는 열 별칭이 파서 오류를 냄 | SQL 키워드이기 때문입니다. `AS minutes`라고 쓰거나 따옴표로 감싸세요: `SELECT count(*) AS "minutes" FROM events` |
| 테이블이나 기록 항목을 클릭했더니 SQL이 사라짐 | 그 클릭은 에디터 버퍼 전체를 바꿉니다. 임시 작업에는 새 쿼리 탭을 사용하세요 |
| 내보내기가 조용히 파일을 바꿔 버림 | 내보내기는 묻지 않고 지정한 경로에 씁니다. 새 이름을 고르세요 |

## S3

| 증상 | 원인과 해결 |
| --- | --- |
| S3 자격 증명이 사라짐 | 설계상 세션 동안에만 유지되며, 데이터베이스를 열거나 전환하면 지워집니다. S3을 다시 설정하세요 |
| 오프라인에서 S3 설정이 실패함 | 첫 사용 시 `INSTALL httpfs`가 실행되며 확장 기능을 내려받습니다. 한 번 연결하면 캐시됩니다 |
| 임시(STS) 자격 증명이 거부됨 | 세션 토큰을 보내지 않습니다. 수명이 긴 키를 사용하세요 — [S3와 httpfs](s3.md#limitations)를 참고하세요 |
| 버킷이 실제보다 작아 보임 | 목록은 단계마다 1,000개에서 멈춥니다. 대신 `'s3://bucket/prefix/*.parquet'` 같은 글롭으로 쿼리하세요 |

## 대시보드

| 증상 | 원인과 해결 |
| --- | --- |
| 대시보드 차트가 쿼리가 읽기 전용이어야 한다고 함 | `.dash` 쿼리가 쓰기를 시도했습니다(DDL, DML, `COPY`, `ATTACH` 등). 대시보드는 읽기 전용 문만 실행하므로 준비 작업은 SQL 에디터로 옮기세요 |
| 에이전트가 내 주석을 보지 못함 | 주석은 어디로도 전송되지 않습니다. 에이전트가 직접 읽어야 합니다. `ducklocal comments FILE`을 실행하게 하거나, [공식 스킬](cli.md#install-the-official-skill)이 있다면 "FILE의 주석을 처리해 줘"라고 요청하세요 |
| 에이전트의 답변이나 수정이 보이지 않음 | 창은 스펙과 `FILE.comments.json`을 1초 안에 따라갑니다. 더 이상 검증되지 않는 스펙은 마지막으로 동작한 대시보드를 그대로 두고 그 위에 이유를 표시합니다. **스펙 보기**를 열어 파일을 확인하세요 |
| 대시보드의 `PIVOT`이 거부됨 | `SELECT`나 `WITH` 안에 중첩된 `PIVOT`은 값을 지정해야 합니다. `PIVOT t ON channel IN ('Web', 'Store') USING sum(revenue)`처럼 나열하거나, 쿼리를 `PIVOT`으로 시작하세요 |

## 모양

| 증상 | 원인과 해결 |
| --- | --- |
| 실행할 때마다 테마가 밝게 초기화됨 | 테마는 실행 사이에 저장되지 않습니다. 언어는 저장됩니다 |
| 텍스트나 아이콘이 너무 작거나 큼 | 제목 표시줄의 **Aa** 버튼이나 ⌘+ / ⌘− / ⌘0을 사용하세요. [인터페이스 크기](settings-and-data.md#interface-size)를 참고하세요 |
| 인터페이스 언어가 잘못됨 | 제목 표시줄의 `EN` / `中` 버튼을 사용하세요. 선택은 기억됩니다 |

## 처음부터 다시 시작

기록, 기억된 파일, 열린 탭, 설정을 지우려면 DuckLocal을 종료하고 앱 데이터
디렉터리를 삭제하세요:

```bash
rm -rf ~/Library/Application\ Support/DuckLocal
```

데이터 파일은 절대 건드리지 않습니다. DuckLocal 자체 기록만 제거됩니다. 그곳에
무엇이 저장되는지는 [설정과 앱 데이터](settings-and-data.md)를 참고하세요.
