The ErrorYou are trying to enable a popular PostgreSQL feature like uuid-ossp for unique identifiers or pg_trgm for fuzzy searching. Instead of a success message, your SQL console throws a wall of red text:
ERROR: extension "uuid-ossp" does not exist
This happens because PostgreSQL keeps its core engine lean. While many extensions are "standard," their physical files often live in a separate package that isn't installed by default. If the .so or .control files are missing from your server's library directory (usually /usr/lib/postgresql/<version>/lib/), Postgres won't know they exist.
Why This HappensPostgreSQL extensions require three things to work: physical files on the disk, a superuser to register them, and the correct database context. You’ll typically run into this error for one of these reasons:
- Missing Contrib Package: The "contrib" modules—a collection of extra tools—were skipped during the initial database installation.- Wrong Database: You are connected to the
postgresmaintenance database instead of your actual application database.- Version Mismatch: You installed the contrib package for PostgreSQL 14, but your server is actually running version 16.## Step-by-Step Fix### Step 1: Install the PostgreSQL Contrib ModulesMost Linux distributions split PostgreSQL into several packages. To fix the missing files, you must install the specific contrib bundle for your version.
On Ubuntu or Debian:Check your version first with psql --version. If you are running version 15, run:
sudo apt-get update
sudo apt-get install postgresql-contrib-15
On RHEL, CentOS, or AlmaLinux:Use dnf or yum to grab the matching package:
# For PostgreSQL 16
sudo dnf install postgresql16-contrib
You don't need to restart the entire database service after this, though it's a good habit to verify the installation immediately.
Step 2: Verify the Extension is AvailableBefore running the install command again, check if PostgreSQL can now see the files. Run this query in your terminal:
SELECT name, default_version, installed_version
FROM pg_available_extensions
WHERE name = 'uuid-ossp';
If the default_version column is populated (e.g., 1.1), the files are ready. If installed_version is null, the extension is available but hasn't been activated in this specific database yet.
Step 3: Activate the ExtensionExtensions are database-specific. If you enable uuid-ossp in your test_db, it won't automatically work in your production_db. Switch to your target database and run the creation command:
-- Connect to your specific app database
\c my_app_db
-- Register the extension
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
Step 4: Handling Docker EnvironmentsThe official postgres Docker image usually includes contrib modules by default. However, if you are using a -slim or -alpine tag, they might be missing. Add this line to your Dockerfile to ensure they are always present:
FROM postgres:16
RUN apt-get update && apt-get install -y postgresql-contrib-16 && rm -rf /var/lib/apt/lists/*
Fixing for Cloud Environments (AWS RDS / Azure)You cannot install OS-level packages on managed services like AWS RDS. Fortunately, AWS already includes these files. If you get this error on RDS, it's usually a permissions issue. Ensure your user has the rds_superuser role. For some specific extensions (like pg_partman), you may also need to add the extension name to the shared_preload_libraries list in your RDS Parameter Group and reboot the instance.
Verification: Testing the FixConfirm everything is working by generating a version 4 UUID:
SELECT uuid_generate_v4();
A successful result looks like this: f47ac10b-58cc-4372-a567-0e02b2c3d479. If you see that 36-character string, you're good to go.