Context

PyMongo 4.18 adds GA support for Queryable Encryption prefix/suffix/substring queries, which per the changelog "requires libmongocrypt 1.20.0 or later".

Nothing in the shipped code enforces or reports that requirement, so users on an older libmongocrypt get an opaque native error instead of an actionable one.

No libmongocrypt floor is expressed anywhere in package metadata, and check_min_pymongocrypt() does not check it. a user on pymongocrypt 1.18.1 with an older bundled libmongocrypt passes every install-time check, then calls encrypt(..., string_opts=...) and receives whatever error libmongocrypt raises.

The test suite already models this correctly
test/test_encryption.py:3331  _libmongocrypt_at_least(), reading pymongocrypt.libmongocrypt_version().
test/test_encryption.py:3469  _require_ga(), which skips GA string tests when libmongocrypt is too old. So the constraint is precisely expressed in tests and entirely absent from the shipped code path.

Definition of done

in the StringOpts / _resolve_string_opts path, check pymongocrypt.libmongocrypt_version() using the same logic as the tests and raise ConfigurationError naming 1.20.0 explicitly.

Pitfalls

PYTHON-5540 ("Fix usage of text_opts for older versions of pymongocrypt") was a bug of exactly this shape for the preview-era text_opts parameter, and was backported to v4.15.