neondatabase/neon · error

library {} is not found

Error message

library {} is not found

What it means

Thrown by RemoteExtSpec::get_ext() in neon's compute_api when is_library is true and the library name (after stripping any .so / .so.N suffix with regex \.so.*) is not a key in the RemoteExtSpec.library_index map. library_index maps raw shared-library names to the extension that provides them, and it is built from the remote extension archive listing sent by the control plane. A miss means the compute's extension spec simply does not know which extension ships that library.

Source

Thrown at libs/compute_api/src/spec.rs:403

    pub fn get_ext(
        &self,
        ext_name: &str,
        is_library: bool,
        build_tag: &str,
        pg_major_version: &str,
    ) -> anyhow::Result<(String, RemotePath)> {
        let mut real_ext_name = ext_name;
        if is_library {
            // sometimes library names might have a suffix like
            // library.so or library.so.3. We strip this off
            // because library_index is based on the name without the file extension
            let strip_lib_suffix = Regex::new(r"\.so.*").unwrap();
            let lib_raw_name = strip_lib_suffix.replace(real_ext_name, "").to_string();

            real_ext_name = self
                .library_index
                .get(&lib_raw_name)
                .ok_or(anyhow::anyhow!("library {} is not found", lib_raw_name))?;
        }

        // Check if extension is present in public or custom.
        // If not, then it is not allowed to be used by this compute.
        if !self
            .public_extensions
            .as_ref()
            .is_some_and(|exts| exts.iter().any(|e| e == real_ext_name))
            && !self
                .custom_extensions
                .as_ref()
                .is_some_and(|exts| exts.iter().any(|e| e == real_ext_name))
        {
            return Err(anyhow::anyhow!("extension {} is not found", real_ext_name));
        }

        match self.extension_data.get(real_ext_name) {
            Some(_ext_data) => Ok((

View on GitHub (pinned to 8f60b04da4)

Solutions

1. Check the exact library name after .so-suffix stripping against the library_index keys of the RemoteExtSpec (dump the spec JSON) to see what is actually available
2. Remove the library from shared_preload_libraries (or the LOAD statement) in the compute spec, or install/upload the extension so the control plane adds it to library_index
3. If the extension exists but is missing from custom_extensions, register it as a custom extension so its libraries get indexed
4. After fixing the extension set, retry the operation that built the compute spec

Example fix

# before (spec)
shared_preload_libraries = 'pg_stat_statements, timescaledb'
# but library_index has no "timescaledb" key

# after
shared_preload_libraries = 'pg_stat_statements'  # or add timescaledb to available extensions

// Check the library resolves before calling get_ext:
fn library_resolves(spec: &RemoteExtSpec, lib: &str) -> bool {
    let raw = Regex::new(r"\.so.*").unwrap().replace(lib, "").to_string();
    spec.library_index.contains_key(&raw)
}

// Inspect the error string to separate 'unknown library' from allow-list/data errors:
match spec.get_ext(lib, true, tag, ver) {
    Ok((name, path)) => { /* download */ }
    Err(e) if e.to_string().starts_with("library") => {
        // skip or report the unknown shared library, keep starting the compute
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: get_ext("pg_stat_statements.so", true, ...) or get_ext("vector.so.3", true, ...) when "pg_stat_statements" / "vector" is not a key in library_index; also any shared_preload_libraries / LOAD of a library that has no corresponding entry in the spec's library index.

Common situations: A shared_preload_libraries entry for a library whose extension is not present in the tenant's available extension set; custom extensions uploaded to the control plane without the library mapping; version skew between the compute image and the remote extension index after an upgrade; typos in the library name in the compute spec.

Related errors

• extension {} is not found
• real_ext_name {} is not found
• pg_ctl failed, exit code: {}, stdout: {}, stderr: {}
• no grpc_url for shard {shard_index}
• no libpq_url for shard {shard_index}

AI-assisted analysis of neondatabase/neon@8f60b04da4 (2026-08-16). Data as JSON: /api/errors/c13873a706d1efe9. Report an issue: GitHub.