duckdb.IOException: Could not open file

TL;DR

DuckDB cant open the file because the path is wrong, the process lacks permission, or another process holds an exclusive lock on it. Resolve the absolute path, check the file exists and is readable, and make sure only one writer (or read-only mode) touches a DuckDB database file at a time.

duckdb.IOException: Could not open file

Use this when

• duckdb.connect("file.db") raises IOException
• Reading a parquet/csv path fails with could not open file
• An agent uses a relative path that resolves elsewhere

Not for this skill when

• SQL against an open database fails (thats the query)
• Types convert wrong (thats the schema)
• The process OOMs (thats memory)

Steps

1. Resolve the path the way DuckDB sees it:

import os
print(os.path.abspath("data.duckdb"))
print(os.path.exists(os.path.abspath("data.duckdb")))

Expected output: the absolute path and whether it exists. Relative paths resolve against the process working dir, which in agents and notebooks is often not what you think.

2. Check permissions and locks on the file:

ls -la /path/to/data.duckdb
lsof /path/to/data.duckdb

Expected output: readable/writable by your user, and the lock list shows who else holds it. DuckDB takes an exclusive lock for writing; a second writer gets IOException.

3. If another process holds the write lock, open read-only:

con = duckdb.connect("/path/to/data.duckdb", read_only=True)

Expected output: the connection opens. Multiple readers are fine; only one writer at a time.

4. For data files (parquet/csv), check the glob actually matches:

import glob
print(glob.glob("/data/exports/*.parquet")[:3])

Expected output: real file paths. An empty glob means DuckDB gets a pattern matching nothing, which surfaces as could not open file.

Variant phrasings

could not open file on a parquet read that worked yesterday

The file was moved, renamed, or the mount dropped. Check the path exists right now, not yesterday.

works locally, fails in the container

The file isnt mounted into the container or the path differs inside it. Check the volume mounts.

Why it happens

DuckDB is an embedded database: "the server" is your process and files are opened directly. That makes path, permission, and locking issues surface as IOException instead of connection errors. Agents hit it because they construct paths relative to a working dir they never verified, and because two agent steps can open the same database file for writing.

Edge cases

• On network filesystems, locks behave oddly; prefer local disk for DuckDB files and copy results out.
• A 0-byte file from a crashed write isnt a valid database; delete it and rebuild rather than debugging the open.
• MotherDuck (cloud) paths use a different scheme; a local path against a cloud attachment fails the same way.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstupNoIpVRC826oCSQkp4_g