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.).

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
• Could not extract warehouseId from httpPath
• drivername is required property
• Missing httpPath in JDBC URL
• Please download and place databricks-jdbc

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

Appendix: 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)