## TL;DR

The version pinned in packages.yml does not exist in the registry (or the registry moved). Check the package's real version list, pin one that exists, delete the stale entry from package-lock.yml if present, and re-run dbt deps.

## Error

```text
dbt deps: package version not found
```

## Steps

1. Open packages.yml and note the package name and pinned version or range.
   Expected: You have the exact requirement, e.g. version: 1.2.3 or a range.

2. Check the package hub (hub.getdbt.com) listing for the package and its published versions.
   Expected: You see whether 1.2.3 was ever published, yanked, or never existed.

3. Pin a version that exists, preferably the latest compatible with your dbt-core. If a package-lock.yml exists, delete it so the new pin resolves fresh.
   Expected: packages.yml references a real version.

4. Run dbt deps and then dbt compile to confirm the package loads.
   Expected: Packages install, compile succeeds.

## When to use

- dbt deps fails saying a package version was not found
- a version range that used to resolve now fails (old versions yanked)
- after copying packages.yml from another project with different dbt-core

## When not to use

- git authentication errors on git-based packages (that is credentials, not the registry)
- network timeouts reaching the hub (that is connectivity)
- the package installs but a macro inside it fails (that is macro code, different fix)

## Tool compatibility

- dbt deps resolves from hub.getdbt.com for registry packages
- package-lock.yml pins exact resolved versions; delete to re-resolve
- dbt-core version compatibility is listed per package release

## Variant phrasings

### package version not found after dbt upgrade
The pinned version may cap dbt-core below your new version. Bump the package pin to a release supporting your dbt-core.

### version not found for a git package
Git packages use revision, not version. Check the tag or commit exists in the repo; a deleted branch breaks the pin.

## Why it happens

The registry only serves versions the maintainer published. Pins copied between projects, ranges that exclude everything compatible, and yanked releases all produce this. dbt will not guess a nearby version; it fails loudly.

## Edge cases

- A too-tight range like 1.0.x-only fails if every 1.0.x release was yanked; widen the range or pin an exact version that exists.
- Private registries need the registry URL configured; otherwise dbt looks on the public hub and will not find your package.

## Provenance

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