TL;DR: The OpenSSL upgrade moved the development libraries, so the linker can no longer find libssl even though OpenSSL itself works fine. Point the build at the new location by setting OPENSSL_DIR before running cargo build. On Linux, installing the OpenSSL dev package achieves the same thing.

```text
error: cannot find -lssl
```

1. Locate the new OpenSSL install: on macOS run `brew --prefix openssl`; on Linux run `ldconfig -p | grep libssl`.
   Expected: you get a directory path whose lib folder actually contains libssl.
2. On macOS with Homebrew, make sure OpenSSL is installed: `brew install openssl`.
   Expected: install completes and prints the installation prefix.
3. Point the build at it: `export OPENSSL_DIR=[the prefix from step 1]`, then run `cargo build` in the same shell.
   Expected: the build links successfully with no -lssl error. If it still fails, also set OPENSSL_LIB_DIR to the lib folder and OPENSSL_INCLUDE_DIR to the include folder.
4. On Debian or Ubuntu instead: `apt-get install -y libssl-dev`, then rebuild.
   Expected: headers land in the standard include path and the build succeeds with no extra env vars.
5. Alternative when you cannot touch the system: enable the vendored feature on the openssl-sys dependency so it builds OpenSSL from source.
   Expected: the build succeeds with no system OpenSSL required, at the cost of a longer compile.

## Use this when
- The build fails with the exact "cannot find -lssl" message.
- The failure started right after an OpenSSL upgrade on the machine or image.
- openssl-sys appears in the dependency tree (check with `cargo tree -i openssl-sys`).

## Not for this skill when
- The openssl-sys build script fails with a different inner error (for example a missing C compiler); that is a separate problem.
- You get TLS errors at runtime; the build already succeeded, so linking is fine.
- The vendored build fails because perl or a C compiler is missing; install those first.

## Variant phrasings
- "cargo cannot find -lssl macOS"
- "openssl-sys ld cannot find lssl after upgrade"
- "rust build error cannot find -lssl ubuntu"
- "linking with cc failed cannot find -lssl"

## Why it happens
openssl-sys links against the system OpenSSL at build time. Package managers install new OpenSSL majors side by side (for example openssl@3 next to openssl@1.1) and eventually remove the old library directory. The linker search path still points at the old location, so it reports that libssl is missing even though a newer OpenSSL is installed elsewhere.

## Edge cases
- pkg-config can also locate OpenSSL, but the OPENSSL_DIR env vars take precedence; conflicting settings cause confusing failures, so set one mechanism.
- Cross-compilation needs the target's OpenSSL dirs, not the host's.
- Pin the OpenSSL dev package version in CI images so a base-image upgrade does not surprise you again.
- The vendored feature downloads the OpenSSL source at build time, so it needs network access during the build.

## Provenance

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