Help! I'm seeing "require-dbt-version was unexpected"

Archive
1

What happened?

Hey there - require-dbt-version is new in 0.13.0! If you’ve included this config in your project, make sure you’ve updated to version 0.13.0 wherever you’re running dbt.

If this config is coming from a dependency like dbt-utils, I’d recommend pinning your package to a specific revision.

What does that mean?

Glad you asked! The dbt deps command will pull in the latest code of a package, given the revision that you’ve specified in your packages.yml file. If you’ve specified master as your revision in your packages.yml file, then dbt will pull the latest version of master from the specified package when you run dbt deps. This probably isn’t desirable, as it means that the code that runs in your project can change out from under you.

Instead, you should always pin your packages to a specific revision. In practice, that looks like:

packages:
  - git: "https://github.com/fishtown-analytics/dbt-utils.git"
    revision: 0.1.22

The revision: 0.1.22 line points to a specific release of the dbt-utils package. You can find more information about pinning a package to a specific version in the docs.

Why did this happen?

As we build new functionality into dbt, we’ll want to leverage it in open source packages like dbt-utils. The require-dbt-version config is going to be super helpful here, as it’s possible that the behavior of dbt will change between versions. The require-dbt-version config will help ensure that the packages that dbt is running are compatible with the installed version of dbt.

Unfortunately, versions of dbt < 0.13.0 don’t expect to see this config, and raise an exception accordingly. As they say: the best time to require a specific dbt version was 10 releases ago; the second best time is now. Check out the docs on require-dbt-version here.

1 Like
2

We recently released version 0.1.23 of dbt-utils, which included the require-dbt-version config.

Some projects are now getting this error, even though dbt-utils is not included in the packages.yml file. This is likely because dbt-utils is a dependency of a package already included in your project. This is the case for lots of our packages, but for this example, I’ll use the Segment package.

You can tell if dbt-utils is installed as a dependency of another package by checking the packages.yml file for that package… For example, the Segment package installs dbt-utils like so:

packages:
 - package: fishtown-analytics/dbt_utils
   version: '>=0.1.20'

Since the dbt-utils version here has a >= for the version number, when you run dbt deps, the latest version of the package will get installed. As of a few days ago, this means v0.1.23 will be installed, which will cause an error if you aren’t using dbt>=0.13.0 ,

To overcome this error you have two options:

  1. Upgrade your dbt version locally and in your production deployment (reach out on Intercom if you need help with this for dbt Cloud), or:
  2. Add dbt-utils as a direct dependency to your project, and ensure that it’s pinned to exactly 0.1.22 (which doesn’t have the “require-dbt-version” config). For example, if you have the Segment package installed, updated your packages.yml file to look like this:
packages:
  - package: fishtown-analytics/segment
    version: 0.2.3
  - package: fishtown-analytics/dbt_utils
    version: 0.1.22

:point_up: this packages.yml file uses the package syntax, which helps with version resolution. This means that dbt understands that >=0.1.20 (as specified in the Segment package), and 0.1.22 (as specified in your project) means that it needs to install exactly 0.1.22.