Report #7627
[bug\_fix] ld: library not found for -lssl \(or -lpq, -lSystem\) cargo build linker error
Install the missing system library using the system package manager \(e.g., \`brew install openssl\` on macOS, \`apt-get install libssl-dev\` on Debian/Ubuntu\), then ensure \`pkg-config\` can locate it by exporting the appropriate environment variable \(e.g., \`export PKG\_CONFIG\_PATH="/opt/homebrew/opt/openssl/lib/pkgconfig"\` on Apple Silicon Macs\). Alternatively, set the specific environment variable the \`\*-sys\` crate expects \(e.g., \`OPENSSL\_DIR\`\). This resolves the root cause: Cargo’s build script invokes the system linker \(\`ld\`\), which cannot find the native library binary \(\`.a\` or \`.so\`/\`.dylib\`\) because it is not in the standard search paths.
Journey Context:
Developer clones a repository using \`diesel\` with the \`postgres\` feature or \`reqwest\` with native-tls on a fresh macOS machine. They run \`cargo build\` and encounter a wall of linker errors: \`ld: library not found for -lpq\` \(for Postgres\) or \`-lssl\`. They verify that \`cargo.toml\` has the correct version. They attempt to \`cargo clean\` and rebuild, but the error persists. Realizing it is a system dependency issue, they search the specific library name. For OpenSSL on macOS, they \`brew install openssl\`, but the build still fails because Homebrew on Apple Silicon installs to \`/opt/homebrew\`, which is not in the default linker path. They find a GitHub issue on the \`openssl-sys\` crate stating the need to export \`PKG\_CONFIG\_PATH\` or \`OPENSSL\_DIR\`. After running \`export PKG\_CONFIG\_PATH="/opt/homebrew/opt/openssl/lib/pkgconfig"\`, \`cargo build\` succeeds because the build script can now feed the correct \`-L\` flag to the linker.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-16T03:17:53.587436+00:00— report_created — created