Why does it say "missing: _DIR" specifically?

Q: Why does it say "missing: _DIR" specifically?

` _DIR` is the cache variable CMake uses to remember where it found the package’s config file. "missing" means it never found ` Config.cmake` anywhere it searched, so the variable was never set.

CMake "Could NOT find <Package> (missing: <Package>_DIR)"

A find_package() call could not locate a dependency. CMake looked for the package’s config file or its <Package>_DIR variable and found neither - the library’s development files are not installed or not on the search path.

What this error means

CMake configure aborts with "Could NOT find <Package>" and a "missing: <Package>_DIR" hint. The same project configures locally where the dependency is installed, but fails on a bare CI image.

CMake output

CMake Error at CMakeLists.txt:8 (find_package):
  Could NOT find OpenSSL (missing: OPENSSL_INCLUDE_DIR OPENSSL_CRYPTO_LIBRARY)
  (Required is at least version "1.1.1")

Common causes

Development package not installed

A runtime library may be present, but find_package() needs the -dev/-devel package that ships the headers and the CMake config (e.g. libssl-dev for OpenSSL). On a slim CI image it is absent.

Package installed outside CMAKE_PREFIX_PATH

The dependency lives in a non-standard prefix (a custom /opt path, a vendored build, a Homebrew cellar) that CMake’s default search does not cover, so it cannot find <Package>Config.cmake.

How to fix it

Install the development package

Add the -dev/-devel package that provides the headers and CMake config before configuring.

Terminal

# Debian/Ubuntu
apt-get update && apt-get install -y libssl-dev
cmake -S . -B build

Point CMake at the install prefix

When the dependency lives in a custom location, add its prefix so find_package() can see the config file.

Terminal

cmake -S . -B build -DCMAKE_PREFIX_PATH=/opt/openssl
# or set <Package>_DIR directly at the config file
cmake -S . -B build -DOpenSSL_DIR=/opt/openssl/lib/cmake/OpenSSL

Confirm what find_package is looking for

Re-run with --debug-find to see every directory CMake searched.
Check whether the package ships a Find<Package>.cmake module or a <Package>Config.cmake config - they search differently.
For pkg-config-based packages, ensure pkg-config and the .pc file are installed.

How to prevent it

Install all -dev/-devel dependencies in the runner image, not ad hoc.
Pass CMAKE_PREFIX_PATH for any dependency in a custom prefix.
Pin dependency versions so find_package(... REQUIRED <version>) stays satisfiable.

Frequently asked questions

Why does it say "missing: <Package>_DIR" specifically?

<Package>_DIR is the cache variable CMake uses to remember where it found the package’s config file. "missing" means it never found <Package>Config.cmake anywhere it searched, so the variable was never set.