## TL;DR
dbt deps clones the git repo you named and then checks out the revision string in packages.yml exactly as written. A ref not found error means that branch, tag, or commit does not exist in that repo under that name, the repo URL points somewhere else than you think, or a private repo was cloned without the credential that can see the ref. List the remote refs, correct the revision to a real one, and pin a tag or commit for reproducibility.

```text
dbt packages install failed: git package ref not found
```

## Use this when
- dbt deps fails naming a git package and a revision that was not found.
- The failure started after editing packages.yml or after the package repo was reorganised.
- The package installs on one machine and fails in CI or dbt Cloud.

## Not for this skill when
- The package is from the dbt hub and the error is a version conflict. That is range resolution, not a git ref.
- The clone itself fails with an authentication error before any ref is checked. Fix access first.

## Steps
1. Copy the exact git URL and revision from packages.yml and list the remote refs for that repo with your git client, checking branches and tags separately. Note whether the revision exists and under which kind. Verify: the existence and kind of the ref are proven against the remote
2. Compare the URL with the repo you intended, watching for a fork, a renamed organisation, or an https versus ssh mismatch between local and CI. Note any difference. Verify: the repo identity is confirmed
3. Correct packages.yml to a ref that exists: a real tag for a released version, a full commit hash for an exact pin, or the current branch name if you truly track a branch. Note the new value. Verify: the config names a real, deliberate ref
4. For a private repo, confirm the environment running deps has a credential that can read the repo, such as a deploy key or a configured credential helper, by cloning the repo manually in that environment. Note the clone succeeds there. Verify: access in the failing environment is verified directly
5. Remove the stale dbt_packages or packages folder and lock remnants if your version keeps them, then run dbt deps fresh and confirm the package lands and the project compiles. Note the install completes. Verify: a clean install from scratch works

## Variant phrasings
### dbt deps git revision not found packages.yml
The config file phrasing.
### dbt package install failed branch does not exist
The branch rename version of the failure.

Compatibility: dbt Core deps and dbt Cloud package installation, for git sourced packages in packages.yml. Hub packages resolve through the hub index and fail differently.

## Why it happens
Packages.yml revision strings are not version constraints for git packages, they are literal refs handed to git. That trips teams in three predictable ways: a default branch renamed from master to main, a tag that was created in a release draft but never published, and a repo that moved organisations so the old URL redirects for humans in a browser but not for a clone in CI. Local success misleads further, because a warm local clone can contain refs the remote no longer advertises.

## Edge cases / pitfalls
- Pinning a branch makes builds move under you when the branch advances. Pin tags or commits for anything that runs in production.
- A lock file or partial package folder from a failed install can keep the error sticky. Clean it before judging a fix.
- Forks used for a quick patch drift from upstream quietly. Put an expiry note on any fork pin.
- If the ref exists but is a lightweight versus annotated tag distinction in your tooling, a full commit hash pin sidesteps the whole class of problem.

## Provenance

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