## TL;DR
Copy the file local before profiling, or profile it where it sits with a local process: profiling a DuckDB database file over a network mount pays network latency for every page read, so the agent must work on a local copy or a snapshot. DuckDB reads its database file in pages on demand. Over a network mount each page is a round trip, and a profiling pass touches most pages, turning minutes of local work into a timeout.

```text
agent timed out when agent tried to profile duckdb database file over network mount error
```

## Use this when
- The check or run fails with this symptom: an agent times out profiling a DuckDB database file over a network mount.
- You are working on an agent workflow profiling DuckDB database files stored on shared or network drives and the failure repeats on the same data or configuration.
- You need the failing rows, rule, or stage isolated before changing thresholds or code.

## Not for this skill when
- A small database file that still times out, where the cause is a locked file or a competing writer rather than the mount.
- The error text names a different tool, stage, or root cause. Match the verbatim error first and use that skill.

## Steps
1. Check the file size and where it is mounted. Verify: the file is large and accessed over a network filesystem
2. Copy the file to local disk, or take a snapshot copy if another process may write it. Verify: a local copy exists with the same size and checksum
3. Run the profiling against the local copy. Verify: profiling completes inside the limit
4. Compare a few profile values against a direct query on the original file. Verify: values match, so the copy was consistent
5. Record the copy step in the workflow for any database file over an agreed size. Verify: network profiling is not attempted again

## Variant phrasings
### agent timed out profile duckdb database network mount
The shorter phrasing focused on the named failure.
### duckdb file over network mount profiling slow
The symptom phrasing a searcher tries next.
### duckdb profiling timeout network file fix
The variant naming the failing stage or tool directly.

Compatibility: DuckDB database files, network filesystems, agent profiling workflows

## Why it happens
Embedded database files assume local disk latency. Network mounts add milliseconds per read where local storage adds microseconds, and profiling is one of the most read-heavy operations there is, so the gap compounds until the agent deadline arrives first.

## Edge cases / pitfalls
- Copying a live database file can capture a torn state; snapshot or stop the writer, or use the DuckDB export path for a consistent copy.
- A read-only open over the mount still pages through the network; read-only does not mean read-free.

## Provenance

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