nocobase/nocobase · critical · Error

Unable to connect to the database

Error message

Unable to connect to the database

What it means

Database.auth() attempts an initial connection using async-retry; after all retry attempts (numOfAttempts) are exhausted, the underlying driver error is wrapped and rethrown as 'Unable to connect to the database'. The real cause is attached as error.cause — inspect it for credentials, host, port, or server-down details.

Source

Thrown at packages/core/database/src/database.ts:887

        });
        const nextDelay = startingDelay * Math.pow(timeMultiple, attemptNumber - 1);
        attemptNumber++;
        if (attemptNumber < (retry as number)) {
          this.logger.warn(`will retry in ${nextDelay}ms...`, { method: 'auth' });
        }
        throw error; // Re-throw the error so that backoff can catch and handle it
      }
    };

    try {
      await backOff(authenticate, {
        numOfAttempts: retry as number,
        startingDelay: startingDelay,
        timeMultiple: timeMultiple,
        maxDelay: 30 * 1000,
      });
    } catch (error) {
      throw new Error(`Unable to connect to the database`, { cause: error });
    }
  }

  /**
   * @internal
   */
  async checkVersion() {
    return process.env.DB_SKIP_VERSION_CHECK === 'on' || (await checkDatabaseVersion(this));
  }

  /**
   * @internal
   */
  async prepare() {
    if (this.isMySQLCompatibleDialect()) {
      const result = await this.sequelize.query(`SHOW VARIABLES LIKE 'lower_case_table_names'`, { plain: true });

      if (result?.Value === '1' && !this.options.underscored) {

View on GitHub (pinned to fa42722fef)

Solutions

1. Read error.cause (or error.original) for the actual driver-level reason
2. Verify DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_DATABASE values by connecting with psql/mysql CLI or a GUI client
3. Ensure the database server is running and reachable from the app host (docker-compose healthcheck / depends_on with condition: service_healthy)
4. If the DB starts slowly, increase retry attempts or starting delay passed to auth()

Example fix

// before
await db.auth({ retryAttempts: 1 });
// after
try {
  await db.auth({ retryAttempts: 10, retryDelay: 3000 });
} catch (e) {
  console.error('DB connect failed:', e.cause); // real driver error
  throw e;
}

// preflight: quick TCP check before auth
import net from 'net';
const ok = await new Promise(res => { const s = net.connect(port, host); s.once('connect', () => { s.end(); res(true); }); s.once('error', () => res(false)); });
if (!ok) throw new Error(`DB ${host}:${port} unreachable`);

try {
  await db.auth({ retryAttempts: 10, retryDelay: 3000 });
} catch (e) {
  console.error('DB connection failed:', e.cause ?? e); // surface driver-level cause
  process.exit(1);
}

When it happens

Trigger: db.auth() with wrong DB_HOST/DB_PORT; wrong DB_USER/DB_PASSWORD; database server not running; firewall/network unreachable; database with the given name does not exist; retry count exhausted on a slow server.

Common situations: Docker container starting before the DB container is ready; wrong credentials after rotating passwords; MySQL/Postgres bound to localhost only while the app runs in a container; typo'd connection string.

Related errors

• (dynamic message from checkExternalDbConnection, thrown as E
• Unable to connect to the remote database: ${error.message}
• Unable to connect to the remote database: ${error.message}
• Test connection failed: ${error.message}
• will retry in ${nextDelay}ms...

AI-assisted analysis of nocobase/nocobase@fa42722fef (2026-09-01). Data as JSON: /api/errors/ea17a5378a79c952. Report an issue: GitHub.