Why a monorepo breaks most dbt tooling

The assumption is almost never stated: that cloning the repository puts you in the project directory. It is true of tutorials and of the first repository a team creates. It stops being true the moment the transformation project shares a repository with anything else — infrastructure, an ingestion service, a second project for a second domain.

What goes wrong, in order

• The project file is not found, and the error says the directory is not a project rather than that it looked in the wrong place.
• Or it is found, and the profile is resolved relative to the wrong directory, so the connection fails with a credentials error.
• Or both work, and artefacts are written to a path outside the project, where the next step does not look for them.

The second is the expensive one, because the error message sends everybody to the credentials, and the credentials are fine.

And the related problem: which repository

A team with two repositories connected — one for models, one for platform tooling — creates a second ambiguity that is rarely handled at all. Tooling that picks the most recently updated, or the first one it finds, will silently change its mind when somebody pushes to the other one. The symptom is a scan that suddenly finds no models, in an estate where nothing changed.

Both problems have the same remedy, and it is unglamorous: let people say. Where the project lives, and which repository holds it, are two facts that cannot be inferred reliably and take ten seconds to state. Infer them as a default, by all means — but make the default visible and overridable, because the cost of guessing wrong is paid silently and for weeks.