Troubleshooting

Troubleshooting

Symptom	Cause & fix
function create_hypertable(regclass, name) does not exist	A ::regclass / ::name cast leaked into the SQL. This package never emits casts — if you hand-wrote SQL, pass the relation as a quoted string literal ('"SensorReading"') and use by_range(...).
extension "timescaledb" has already been loaded with another version	Shadow-DB version clash. Ensure the shadow DB is on the same TimescaleDB image and don't pin a VERSION in CREATE EXTENSION.
could not open extension control file	You're on a non-TimescaleDB Postgres image. Use a timescale/timescaledb* image.
function percentile_agg(...) does not exist (or candlestick_agg, counter_agg, time_weight)	The timescaledb_toolkit extension isn't installed. Use the timescale/timescaledb-ha image or Tiger Cloud — see Aggregates & hyperfunctions.
Shadow-DB name rejected (managed/Tiger Cloud)	Set an explicit shadowDatabaseUrl to a dedicated TimescaleDB-capable database.
Views cannot have primary keys	Prisma 7 disallows @@id on views — use @@unique([...]) on the continuous-aggregate view.
relation "sensorhourly" does not exist when refreshing	A mixed-case cagg name was passed unquoted and case-folded. $timescale.refreshContinuousAggregate already quotes it; if calling raw SQL, pass '"SensorHourly"'.
Chunk skipping has no effect	The timescaledb.enable_chunk_skipping GUC must be on at query time, and range stats only exist on compressed chunks — see Hypertables → Chunk skipping.
cannot create continuous aggregate with incompatible bucket width	A hierarchical cagg's outer bucket must be a whole multiple of the inner's.

Limitations

• Relation filters — the models you traverse must be visible to the generator (or supplied via the manual config); a relation to a model the generator can't see isn't available for filtering.
• timeBucket numeric precision — aggregates default to JS number (count → int, sum/avg → double precision), so a default sum beyond 2^53 is float64-rounded. For exact results, opt an aggregate into as: "bigint" / as: "string". (Continuous-aggregate columns use the type you declare on the view model.)
• Continuous aggregates must use @@unique (not @@id) — a Prisma constraint (Prisma 7: "Views cannot have primary keys"), not a limitation of this package.
• Out of scope (for now): vector search (pgvector / pgvectorscale) and BM25 / full-text search.