# Troubleshooting

> Fixes for common DuckLocal problems: ducklocal command not found, files that do not attach, databases that will not open, stuck queries, S3 and dashboards.

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

**[中文](zh/troubleshooting.md)**

Find the symptom, read the cause, and apply the fix. If your issue is not listed, [open an issue](https://github.com/JetSquirrel/DuckLocal/issues) with details on what you did and what happened.

## Installing and launching

| Symptom | Cause and fix |
| --- | --- |
| The app will not open on an Intel Mac | The macOS release is built for Apple silicon only. [Build from source](development.md#build-and-run) on Intel |
| Shortcuts in these docs do nothing on Windows or Linux | Read **Ctrl** for **⌘**: ⌘↵ is Ctrl+Enter there |
| `ducklocal: command not found` | The disk image installs the app, not a command. [Link the binary onto your PATH](getting-started.md#add-command) |
| The terminal is busy while the window is open | Opening the GUI from a terminal runs it in the foreground. Launch from Applications instead, or leave that terminal to it |
| History, settings or remembered files stop being saved | A second DuckLocal is running and holds the app-data file. Quit the other one and relaunch |
| **DuckLocal quit unexpectedly last time** | It crashed, and saved a report in the logs folder. Click **Show report**, and attach it to an [issue](https://github.com/JetSquirrel/DuckLocal/issues) — see [where things are stored](settings-and-data.md#where-things-are-stored) |
| **Update check failed** | Hover it for the reason: offline, a proxy, or a download that did not match its checksum. Click to try again, or download the release from GitHub — see [Update check](settings-and-data.md#update-check) |

## Opening data

| Symptom | Cause and fix |
| --- | --- |
| `File not found` on a path you named | The path does not exist, or is relative to a different directory than you think. Use an absolute path to be sure |
| A folder reports no data files | Nothing under it matched `.csv`, `.tsv`, `.txt`, `.parquet`, `.json`, `.ndjson`, `.jsonl`, `.xlsx`, `.xls`, `.xlsb` or `.ods` |
| A folder produced fewer files than expected | Hidden entries and symlinks are skipped, and one open request attaches at most 256 files. Open subfolders separately |
| A path opened as a database unexpectedly | Any existing file that is not a data file is treated as a DuckDB database. If it will not open, DuckLocal says why; at launch it falls back to memory. See [Opening a database](#opening-a-database) |
| **Not attached …: the database already has a table or view named …** | The database already contains a table or view with the same name as the remembered file. DuckLocal never replaces it. Rename or drop one of the two, or remove the file from **Local files** and open it again to get a new name |
| **Cannot restore relative path …** | A file was remembered by a relative path, which cannot be resolved in a new session. Remove it from **Local files** and open it again |
| A view shows `sales_2` instead of `sales` | Another file or table already had that name, so the new one got a suffix |
| A file's view is stale | Views read the file on every query. If a CSV's columns changed shape, use **Refresh schema** in the sidebar |

## Opening a database {#opening-a-database}

| Symptom | Cause and fix |
| --- | --- |
| The message says the database was created by a newer DuckDB | The file uses a storage format newer than DuckLocal's built-in DuckDB reads. Run the `ATTACH … COPY FROM DATABASE` lines from the message in the DuckDB that created the file, then open the copy. See [When a database will not open](data-sources.md#when-a-database-will-not-open) |
| The message says the database comes from DuckDB v0.9 or earlier | Run `EXPORT DATABASE 'dir'` with the DuckDB that wrote it, then `IMPORT DATABASE 'dir'` in DuckLocal |
| The message says it is a SQLite database | Attach it with **Open → Attach database…** instead of opening it |
| The message says the file is not a DuckDB database | Its extension is not one DuckLocal reads as data, so it was tried as a database. Give it a [supported extension](data-sources.md#supported-file-formats), or read it in SQL, for example `SELECT * FROM read_csv('export.dat')` |
| DuckDB says it could not set a lock on the file | Another program — another DuckDB, a script, a second app — has the database open for writing, and DuckDB lets only one process write a file. Close it there, then open the file again |
| DuckDB says permission denied | Your account cannot read the file, or cannot write it: the main database is opened for writing. Fix the file's permissions, or attach it with **Read-only** checked |
| A database open failed and nothing changed | Expected while DuckLocal is running: a failed open leaves the workspace you had. Read the notification for the reason |
| The status bar tooltip says **readable by DuckDB v1.x+** and a colleague cannot open the file | Their DuckDB is older than that version. They need to upgrade, or you copy the file with an older `STORAGE_VERSION` — see [Which DuckDB can read a database](data-sources.md#storage-version) |

## Attached databases

| Symptom | Cause and fix |
| --- | --- |
| An attached database is missing after a relaunch | Its file was not at the remembered path at launch, so it was skipped. The registration is kept; put the file back and it returns with the next connection |
| **This database is already open, as …** | The file is already the main database, or attached under that name. Query it by that name |
| **Could not attach …: the name … is taken in the open database.** | Something else in the connection already uses the remembered alias — for example a database you attached in SQL under the same name. `DETACH` that one, then reopen the database or relaunch |
| Writing to an attached database fails | It was attached read-only, the default. **Detach database** from the sidebar, then attach it again with **Read-only** unchecked |
| Attaching created an empty database | With **Read-only** unchecked, a DuckDB path that does not exist is created. Detach it, delete the empty file, and check the path |
| A table name without a database finds the wrong table | Names without a database resolve in the default database. Right-click a database and choose **Use as default database**, or write `alias.table` |

## Finder and Quick Look

These are macOS only.

| Symptom | Cause and fix |
| --- | --- |
| Double-clicking a `.parquet` or `.duckdb` file opens another app | That app is already the default. In Finder, **Get Info → Open with**, choose DuckLocal, then **Change All…** |
| Double-clicking a CSV or Excel file does not open DuckLocal | By design: DuckLocal does not take these over. Use **Open With → DuckLocal**, or drop the file on the Dock icon |
| DuckLocal is not offered under **Open With**, or Space shows no DuckLocal preview | macOS has not registered the app yet. Move it to Applications and launch it once. For the preview, then run `qlmanage -r` in Terminal, and check that **DuckLocal Preview** is on under Quick Look in System Settings' extension settings |
| A plain `.json` or Excel file shows no DuckLocal preview | By design: those are left to macOS's own previews. `.jsonl` and `.ndjson` files are previewed |
| The preview shows only 50 rows | By design: a preview never scans the whole file. Open the file in DuckLocal for the rest |
| The preview of a `.duckdb` file shows an error | The preview reads the file with DuckLocal's own DuckDB, so a file from a newer DuckDB fails there too. See [Opening a database](#opening-a-database) |

## Running queries

| Symptom | Cause and fix |
| --- | --- |
| **Run** does nothing | A query is already running. Press **Stop** beside Run, or **⌘.**, to interrupt it |
| A query failed with `Interrupted` | Someone pressed **Stop** (or ⌘.) while it ran. Run it again |
| Part of my SQL has a red wavy underline | The last run failed there. Read the *Query failed* message; the mark clears on the next run |
| **⌘↵** shows the editor instead of running | On the first-run screen, ⌘↵ means "give me an editor". Press it again to run |
| Results stop early with a truncation notice | The 100,000-row or 2,000,000-cell cap was reached. Narrow the query; there is no pagination |
| Timestamps look shifted | The grid renders timestamps in UTC, not local time |
| A `TIMETZ` value has lost its offset, or a `BIT` or `BIGNUM` value looks like bytes | Those types can't be told apart from ordinary values on their way to DuckLocal. `CAST(column AS VARCHAR)` in SQL shows the real value |
| Sorting does not bring in rows beyond the preview | Header sorting only rearranges loaded rows. Use `ORDER BY` in SQL to order the full result before truncation |
| A query needs an extension that is not installed | Missing extensions are no longer downloaded automatically. Install it explicitly in the **Extensions** tab, then load it or rerun the query |
| A query that worked before 0.3.0 says an extension is not installed, or a function does not exist | DuckLocal 0.3.0 runs DuckDB 2.0, which keeps installed extensions per release. Install them again from the **Extensions** tab — see [Extensions](schema-and-history.md#extensions) |
| A bare column alias such as `minutes` causes a parser error | It is a SQL keyword. Write `AS minutes`, or quote it: `SELECT count(*) AS "minutes" FROM events` |
| Clicking a table or history entry wiped my SQL | Those clicks replace the whole editor buffer. Use a new query tab for scratch work |
| An export silently replaced a file | Export writes to the path you give without asking. Choose a new name |

## S3

| Symptom | Cause and fix |
| --- | --- |
| S3 credentials were forgotten | They are session-only by design, and opening or switching a database clears them. Configure S3 again |
| Configuring S3 fails offline | The first use runs `INSTALL httpfs`, which downloads the extension. Connect once, then it is cached |
| Temporary (STS) credentials are rejected | No session token is sent. Use long-lived keys — see [S3 and httpfs](s3.md#limitations) |
| A bucket looks smaller than it is | Listing stops at 1,000 entries per level. Query with a glob such as `'s3://bucket/prefix/*.parquet'` instead |

## Dashboards

| Symptom | Cause and fix |
| --- | --- |
| A dashboard plot says a query must be read-only | A `.dash` query tried to write (DDL, DML, `COPY`, `ATTACH`, …). Dashboards only run read-only statements; move the setup into the SQL editor |
| An agent did not see my comments | Comments are not sent anywhere: the agent has to read them. Ask it to run `ducklocal comments FILE`, or to "address the comments on FILE" if it has the [official skill](cli.md#install-the-official-skill) |
| An agent's reply or edit does not show | The window follows both the spec and `FILE.comments.json` within a second. A spec that no longer validates keeps the last working dashboard up, with the reason above it; open **View spec** to see the file |
| A `PIVOT` in a dashboard is rejected | A `PIVOT` nested inside a `SELECT` or `WITH` must name its values. List them: `PIVOT t ON channel IN ('Web', 'Store') USING sum(revenue)`, or start the query with the `PIVOT` |

## Appearance

| Symptom | Cause and fix |
| --- | --- |
| The theme resets to light on every launch | The theme is not saved between launches; the language is |
| Text or icons are too small or too large | Use the **Aa** button in the title bar, or ⌘+ / ⌘− / ⌘0. See [Interface size](settings-and-data.md#interface-size) |
| The interface is in the wrong language | Use the `EN` / `中` button in the title bar; the choice is remembered |

## Starting over

To clear history, remembered files, open tabs and settings, quit DuckLocal and
remove its app-data directory:

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

Your data files are never touched — only DuckLocal's own records are removed. See [Settings and app data](settings-and-data.md) for what is stored there.