Troubleshooting
Find the symptom, read the cause, and apply the fix. If your issue is not listed, open an issue 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 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 |
| 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 — see 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 |
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 |
| 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
| 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 |
| 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, 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 |
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 |
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 |
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 |
| 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 |
| 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 |
| 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/DuckLocalYour data files are never touched — only DuckLocal's own records are removed. See Settings and app data for what is stored there.