cube-js/cube · error · Error

err.toString()

Error message

err.toString()

What it means

JDBCDriver.testConnection creates a pooled connection to validate configuration; if pool._factory.create() fails, the caught message is rethrown as a new Error(err.toString()). The message is opaque because it wraps whatever the underlying JDBC/Java layer reported (connection refused, auth failure, class not found, etc.).

Source

Thrown at packages/cubejs-jdbc-driver/src/JDBCDriver.ts:225

    for (const [name, value] of Object.entries(this.config.properties)) {
      properties.putSync(name, value);
    }

    return properties;
  }

  public async testConnection() {
    let err;
    let connection;

    try {
      connection = await this.pool._factory.create();
    } catch (e: any) {
      err = e.message || e;
    }

    if (err) {
      throw new Error(err.toString());
    } else {
      await this.pool._factory.destroy(connection);
    }
  }

  protected prepareConnectionQueries() {
    const dbTypeDescription = JDBCDriver.dbTypeDescription(this.config.dbType);
    return this.config.prepareConnectionQueries ||
      dbTypeDescription && dbTypeDescription.prepareConnectionQueries ||
      [];
  }

  protected escapeDialect(): EscapeDialect {
    const dbTypeDescription = JDBCDriver.dbTypeDescription(this.config.dbType);
    if (dbTypeDescription?.escapeDialect) {
      return dbTypeDescription.escapeDialect;
    }

View on GitHub (pinned to 7d981676b3)

Solutions

1. Read the wrapped inner message (err.toString() preserves e.message) to see the underlying JDBC error
2. Verify network reachability to the DB host/port (telnet/nc) and correct URL format
3. Verify credentials and that the drivername class is on the classpath (set customClassPath if using a custom JAR)
4. Fix the root cause and re-run testConnection; only wrap further if you need more context

Example fix

// before: driver class missing from classpath
new JDBCDriver({ drivername: 'com.mysql.cj.jdbc.Driver', url: 'jdbc:mysql://host/db' });
// after: supply the driver jar
new JDBCDriver({ drivername: 'com.mysql.cj.jdbc.Driver', url: 'jdbc:mysql://host/db', customClassPath: '/path/to/mysql-connector-j-8.x.jar' });

// Pre-flight reachability + config check before testConnection
const url = new URL(cfg.url.replace(/^jdbc:postgresql:\/\//, 'http://'));
const net = require('net');
net.connect({ host: url.hostname, port: Number(url.port) })
  .on('connect', function () { this.end(); })
  .on('error', (e) => console.error('DB unreachable:', e.message));
if (!cfg.drivername) throw new Error('drivername missing — testConnection will fail');

try {
  await driver.testConnection();
} catch (e) {
  // e.message here is the raw underlying JDBC error string (from err.toString())
  console.error('JDBC testConnection failed with underlying error:', e.message);
  // inspect for 'Connection refused', 'Access denied', 'ClassNotFoundException' to fix root cause
}

When it happens

Trigger: Calling testConnection() when the JDBC connection cannot be established: unreachable host/port, bad credentials, missing JDBC driver class on the classpath, or a malformed JDBC URL — anything making factory.create() throw.

Common situations: Database down or firewall blocking the port; wrong username/password; missing custom JAR in customClassPath so the drivername class isn't found; typo in jdbc URL.

Related errors

• Connection check failed: ${errorMessage}
• Unexpected stream end before row with names
• Please download and place databricks-jdbc-${OSS_DRIVER_VERSI
• Missing httpPath in JDBC URL
• Could not extract warehouseId from httpPath

AI-assisted analysis of cube-js/cube@7d981676b3 (2026-09-02). Data as JSON: /api/errors/e198a688ddc0a7f3. Report an issue: GitHub.