{"record":{"id":"8680e5b899ffaf2b","repo":"cube-js/cube","slug":"pooltimeouterror","errorCode":null,"errorMessage":"PoolTimeoutError","messagePattern":"PoolTimeoutError","errorType":"exception","errorClass":"PoolTimeoutError","httpStatus":null,"severity":"error","filePath":"packages/cubejs-backend-shared/src/pool.ts","lineNumber":44,"sourceCode":" * Uses composition instead of inheritance because generic-pool doesn't export\n * a Pool class, the Pool type is an interface, not an extendable class.\n */\nexport class Pool<T> {\n  private readonly pool: GenericPool<T>;\n\n  private readonly name: string;\n\n  public constructor(name: string, factory: PoolFactory<T>, options?: Options) {\n    this.name = name;\n    this.pool = genericPool.createPool<T>(factory, options);\n  }\n\n  public async acquire(priority?: number): Promise<T> {\n    try {\n      return await this.pool.acquire(priority);\n    } catch (error) {\n      if (error instanceof Error && error.name === 'TimeoutError') {\n        throw new PoolTimeoutError(this.name);\n      }\n\n      throw error;\n    }\n  }\n\n  public async release(resource: T): Promise<void> {\n    return this.pool.release(resource);\n  }\n\n  public async destroy(resource: T): Promise<void> {\n    return this.pool.destroy(resource);\n  }\n\n  public async drain(): Promise<void> {\n    return this.pool.drain();\n  }\n","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/cube-js/cube/blob/7d981676b36392fec34088b9afab6bdcad40207c/packages/cubejs-backend-shared/src/pool.ts#L26-L62","documentation":"PoolTimeoutError is thrown by the generic resource-pool wrapper's acquire() when the underlying pool's acquire() rejects with an error named 'TimeoutError' — i.e. no resource became available within the pool's configured acquisition timeout. It is a normalized error type so callers can reliably identify pool-exhaustion timeouts. The original TimeoutError is replaced by PoolTimeoutError carrying the pool name.","triggerScenarios":"Calling acquire() (or code that uses it) while all pooled resources are checked out and the wait exceeds the pool's acquire timeout; e.g. too many concurrent queries for a small maxSize pool, or leaked resources never released.","commonSituations":"Database/driver pools sized too small for concurrent load; resources not returned because callers forget to release; long-running operations holding connections longer than the timeout; load spikes during heavy orchestration queries.","solutions":["Increase the pool's maxSize / acquire timeout options in the Pool constructor config.","Fix resource leaks: ensure every acquire is paired with a release, or prefer pool.use(cb) which auto-releases.","Reduce concurrency (query orchestrator limits, queues) so demand fits pool capacity.","Catch PoolTimeoutError specifically and apply backoff/retry at the call site."],"exampleFix":"// before\nconst pool = new Pool(clientFactory, { max: 5 });\n// after\nconst pool = new Pool(clientFactory, { max: 20, acquireTimeout: 30000 });","handlingStrategy":"retry","validationCode":"// pre-check pool saturation if the pool exposes state accessors\n// e.g. if (pool.getBusyCount?.() >= maxSize) await waitForFreeSlot();","typeGuard":"import { PoolTimeoutError } from '@cubejs-backend/shared';\nconst isPoolTimeout = (e: unknown): e is PoolTimeoutError => e instanceof PoolTimeoutError;","tryCatchPattern":"try {\n  const client = await pool.acquire();\n} catch (e) {\n  if (e instanceof PoolTimeoutError) {\n    // backoff and retry acquisition\n  } else {\n    throw e;\n  }\n}","preventionTips":["Size the pool (maxSize) for peak concurrency, not average.","Always release acquired resources; prefer pool.use(cb) for auto-release.","Set an explicit acquire timeout appropriate to workload.","Monitor pool wait times and alert before timeouts occur."],"tags":["pool","timeout","resource-exhaustion","concurrency"],"backgroundTag":"pool-timeout","analyzedSha":"7d981676b36392fec34088b9afab6bdcad40207c","analyzedAt":"2026-09-02T03:45:10.400Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}