Troubleshooting

This page collects common issues that appear across dbverse workflows, primarily in R.

Database lock errors

DuckDB uses file-level locks. A file-backed database can fail to open when another process still has a conflicting connection.

A typical error appears below.

Error: Could not set lock on file "path/to/database.duckdb":
Conflicting lock is held by another process.

Common causes include the following.

• Another R session is connected to the same database.
• Another session or process still has a live connection.
• Multiple scripts are trying to write to the same database at once.

The preferred fix is to close the active connection cleanly.

Note: Disconnecting may make temporary or in-memory objects unavailable. Persist or collect any results you need before disconnecting.

R

proj$disconnect()

DBI::dbDisconnect(con)

Python

⌀

Julia

⌀

For concurrent read-only work, open the DuckDB database in read-only mode.

R

con <- DBI::dbConnect(
  duckdb::duckdb(),
  dbdir = "path/to/database.duckdb",
  read_only = TRUE
)

Python

⌀

Julia

⌀

No active or cached connection

This usually means the project connection was closed or never established.

R

proj$reconnect()

Python

⌀

Julia

⌀

Stale lazy references after restart

Lazy table references depend on a live database connection. Use dbProject pins for objects that need to survive restarts.

R

proj <- dbProject$new(path = "my_project", dbdir = "data.duckdb")
proj$reconnect()

my_data <- proj$pin_read("my_table")

Python

⌀

Julia

⌀

Memory pressure

Avoid collecting large lazy tables. Filter, summarize, or materialize in the analytical database first, and collect only the smaller result.

R

lazy_filtered <- big_table |>
  dplyr::filter(gene == "BRCA1")

result <- dplyr::collect(lazy_filtered)

filtered_data <- proj$pin_write(
  x = lazy_filtered,
  name = "filtered"
)

Python

⌀

Julia

⌀

Slow workflows

Complex lazy query chains can become expensive. Inspect the query plan and materialize important intermediates before reusing them.

R

materialized <- complex_result |>
  dplyr::compute(name = "materialized", temporary = FALSE)

Python

⌀

Julia

⌀

Getting help

• Check the relevant package site in the Index.
• Confirm you are using current development versions from the dbverse GitHub organization.
• Include a minimal reproducible example when filing an issue.