dbt-duckdb: io error on motherduck attach

TL;DR

The attach string or the MotherDuck credential is wrong, or the network path to MotherDuck is blocked. Check the attach database string format, confirm the credential is set and valid, and test the attach in plain duckdb before blaming dbt.

Error

dbt-duckdb: io error on motherduck attach

Steps

1. Test outside dbt first: open the duckdb CLI and run the attach statement by hand with your database name and credential. Expected: You reproduce the io error in isolation, or it works and the problem is dbt-side config.

2. Verify the credential: it should be a valid MotherDuck token with no stray whitespace or quotes. Regenerate it in the MotherDuck UI if unsure. Expected: A fresh, known-good credential.

3. Check the attach string format in your profile or model config: md: followed by the database name, with the credential passed the way dbt-duckdb expects (not pasted into the SQL string). Expected: The attach string matches the documented format exactly.

4. Re-run dbt debug, then the failing dbt command. Expected: Attach succeeds, models build against MotherDuck.

When to use

• dbt-duckdb raises io error on motherduck attach
• first-time MotherDuck setup with dbt
• the credential was rotated and dbt started failing

When not to use

• queries fail after attach succeeds (that is SQL or schema, not the attach)
• local duckdb file errors (no MotherDuck involved)
• the error is a timeout, not an io error

Tool compatibility

• dbt-duckdb adapter with MotherDuck support
• duckdb CLI to test the attach in isolation
• MotherDuck UI to regenerate credentials

Variant phrasings

io error only in CI

CI may block the MotherDuck endpoint or lack the credential env var. Check egress rules and secret injection.

attach works in CLI but fails in dbt

dbt-duckdb builds the attach string from profile fields; a misnamed field means dbt sends a malformed string. Compare field names to the adapter docs.

Why it happens

ATTACH opens a network session to MotherDuck, so it fails like a network call: bad credential, malformed database string, or blocked egress. The io error label is DuckDB's generic way of saying the remote open failed.

Edge cases

• Credentials pasted with a trailing newline are a classic; strip whitespace when storing the value.
• MotherDuck database names are per-account; attaching a database that does not exist yet in your account also errors, create it first.

Provenance

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

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

Thread query: dbt-duckdb: io error on motherduck attach

TL;DR: The attach string or the MotherDuck credential is wrong, or the network path to MotherDuck is blocked. Check the attach database string format, confirm the credential is set and valid, and test the attach in plain duckdb before blaming dbt.