agent's dbt ls failed when agent tried listing models in a monorepo

TL;DR

In a monorepo, dbt ls fails when it runs from the wrong directory or tries to parse every project at once. The agent should cd into the target project (or pass --project-dir), run dbt parse first to surface errors, then scope dbt ls --select to that project.

Error

agent's dbt ls failed when agent tried listing models in a monorepo

Steps

1. Identify the dbt project directory containing the dbt_project.yml for the models you want. Expected: you know the exact project path.
2. Run from that directory, or pass --project-dir [PATH] and --profiles-dir [PATH] explicitly. Expected: dbt operates on the right project.
3. Run dbt parse first and read any errors. Expected: parse errors (the real cause) surface before listing.
4. List with a scoped selector: dbt ls --select [SUBDIRECTORY] --resource-type model. Expected: a clean model list for that project.
5. If projects share packages, ensure dbt deps ran in the right project directory. Expected: package models resolve.

When to use

• dbt ls fails, hangs, or lists the wrong models in a monorepo.
• The repo has multiple dbt_project.yml files.

When not to use

• Single-project repos (plain dbt ls from the project root works).
• The failure is a genuine parse error in a model (fix the model).

Tool compatibility

• dbt Core 1.0 and later, all adapters. --project-dir and --profiles-dir are core flags.

Variant phrasings

dbt run picks the wrong project in a monorepo

Same root cause: the working directory selected the project, not the intent.

dbt ls lists models from every project

Scope with --select on the project path, or run per project directory.

Why it happens

dbt discovers the project from the working directory upward. In a monorepo the agent's cwd may resolve to a parent or sibling project, so commands silently target the wrong graph.

Edge cases

• Symlinked project directories confuse path resolution; use real paths.
• Shared profiles.yml across projects needs the right profile key per project; check dbt_project.yml's profile: field.
• CI in monorepos should set the working directory per job, not rely on repo root.

Provenance

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