TimescaleDB "could not access file timescaledb / extension not found" in CI

By Kaveh Alemi·Latchkey

CREATE EXTENSION fails with "could not open extension control file" or "extension timescaledb is not available" when the TimescaleDB files are missing for the running Postgres major version. The image either lacks the extension or mismatches the server version.

What this error means

CREATE EXTENSION fails with "ERROR: could not open extension control file \".../timescaledb.control\": No such file or directory" or "extension \"timescaledb\" is not available".

ERROR: could not open extension control file
"/usr/share/postgresql/16/extension/timescaledb.control": No such file or directory

Common causes

The extension is not installed for this Postgres version

The control file lives under a version-specific extension directory; if the package for that major version is missing, CREATE EXTENSION cannot find it.

A Postgres image without the TimescaleDB package

A plain postgres image has no timescaledb files at all, so the extension is simply not available.

How to fix it

Use a TimescaleDB image matching the PG version

1. Pick a timescale/timescaledb tag that matches your Postgres major.
2. Confirm the control file exists for that version.
3. Then create the extension.

services:
  db:
    image: timescale/timescaledb:2.16.1-pg16
    env: { POSTGRES_PASSWORD: postgres }
    ports: ['5432:5432']

Verify availability before creating

Check the catalog so a missing package fails with a clear message.

psql -c "SELECT * FROM pg_available_extensions WHERE name='timescaledb';"

How to prevent it

• Match the TimescaleDB image tag to the Postgres major version.
• Query pg_available_extensions before CREATE EXTENSION.
• Pin both server and extension versions for reproducibility.

Frequently asked questions

Related guides

References

• GitHub Actions documentation