# トラブルシューティング

> DuckLocal でよくある問題の解決方法: ducklocal コマンドが見つからない、ファイルがアタッチされない、データベースが開かない、クエリが止まる、S3 とダッシュボード。

Source: https://ducklocal.app/docs/ja/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 を起動するとフォアグラウンドで実行されます。アプリケーションから起動するか、そのターミナルをそのまま占有させてください |
| 履歴、設定、記憶されたファイルが保存されなくなる | 2 つ目の 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` のいずれにも一致するものがありませんでした |
| フォルダーから想定より少ないファイルしか得られない | 隠しエントリとシンボリックリンクはスキップされ、1 回のオープン要求でアタッチされるのは最大 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)を付けるか、SQL で読み取ってください（例: `SELECT * FROM read_csv('export.dat')`） |
| DuckDB がファイルのロックを取得できなかったと表示する | ほかのプログラム（別の DuckDB、スクリプト、2 つ目のアプリ）がデータベースを書き込み用に開いています。DuckDB は 1 つのプロセスだけがファイルに書き込めるようにしています。そこで閉じてから、もう一度ファイルを開いてください |
| DuckDB がアクセスを拒否されたと表示する | アカウントにそのファイルの読み取り権限がないか、書き込み権限がありません（メインのデータベースは書き込み用に開かれます）。ファイルの権限を修正するか、**読み取り専用** をオンにしてアタッチしてください |
| データベースを開くのに失敗し、何も変わらなかった | DuckLocal の動作中は想定どおりです。開くのに失敗しても、それまでのワークスペースがそのまま残ります。理由は通知を確認してください |
| ステータスバーのツールチップに **DuckDB v1.x 以降で読み取り可能** と表示され、同僚がファイルを開けない | 相手の DuckDB がそのバージョンより古いためです。アップグレードするか、古い `STORAGE_VERSION` でファイルをコピーしてください。詳しくは[どの DuckDB がデータベースを読めるか](data-sources.md#storage-version)を参照してください |

## アタッチされたデータベース

| 症状 | 原因と対処 |
| --- | --- |
| 再起動後にアタッチしたデータベースが消えている | 起動時に記憶されたパスにファイルがなかったため、スキップされました。登録は保持されているので、ファイルを元に戻せば次の接続で復帰します |
| **このデータベースはすでに … として開かれています** | そのファイルはすでにメインのデータベースであるか、その名前でアタッチされています。その名前でクエリしてください |
| **アタッチできませんでした …: 名前 … は開いているデータベースで使用されています。** | 接続内の何かがすでに記憶された別名を使っています。たとえば、同じ名前で SQL からアタッチしたデータベースなどです。それを `DETACH` してから、データベースを開き直すか再起動してください |
| アタッチしたデータベースへの書き込みが失敗する | 既定の動作である読み取り専用でアタッチされています。サイドバーから **データベースをデタッチ** し、**読み取り専用** をオフにしてアタッチし直してください |
| アタッチしたら空のデータベースが作成された | **読み取り専用** がオフの場合、存在しない DuckDB のパスは新規作成されます。デタッチして空のファイルを削除し、パスを確認してください |
| データベースを指定しないテーブル名で別のテーブルが見つかる | データベースを指定しない名前は既定のデータベースで解決されます。データベースを右クリックして **既定のデータベースとして使用** を選ぶか、`alias.table` と書いてください |

## Finder とクイックルック

これらは macOS 専用です。

| 症状 | 原因と対処 |
| --- | --- |
| `.parquet` または `.duckdb` ファイルをダブルクリックすると別のアプリが開く | そのアプリがすでに既定になっています。Finder で **情報を見る → このアプリケーションで開く** を選び、DuckLocal を選択してから **すべてを変更…** をクリックします |
| CSV や Excel ファイルをダブルクリックしても DuckLocal が開かない | 仕様です。DuckLocal はこれらの関連付けを奪いません。**このアプリケーションで開く → DuckLocal** を使うか、ファイルを Dock のアイコンにドロップしてください |
| **このアプリケーションで開く** に DuckLocal が出てこない、またはスペースキーでプレビューが出ない | macOS がまだアプリを登録していません。アプリケーションに移動して一度起動してください。プレビューについては、その後ターミナルで `qlmanage -r` を実行し、システム設定の拡張機能にあるクイックルックで **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 階層あたり 1,000 件で止まります。代わりに `'s3://bucket/prefix/*.parquet'` のような glob でクエリしてください |

## ダッシュボード

| 症状 | 原因と対処 |
| --- | --- |
| ダッシュボードのプロットで、クエリは読み取り専用でなければならないと表示される | `.dash` のクエリが書き込み（DDL、DML、`COPY`、`ATTACH` など）を試みました。ダッシュボードは読み取り専用の文だけを実行します。セットアップは SQL エディターに移してください |
| エージェントが自分のコメントを見ていない | コメントはどこにも送信されません。エージェントが読み取る必要があります。`ducklocal comments FILE` を実行するよう依頼するか、[公式スキル](cli.md#install-the-official-skill)を持っていれば「FILE のコメントに対応して」と依頼してください |
| エージェントの返信や編集が表示されない | ウィンドウは spec と `FILE.comments.json` の両方を 1 秒以内に追従します。検証に通らなくなった spec では、最後に動作していたダッシュボードがそのまま表示され、その上に理由が出ます。**spec を表示** を開くとファイルを確認できます |
| ダッシュボードの `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)を参照してください。
