## 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

```text
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/pst_Rf7_riXel6Lj8Yw4V0l9ow