What causes "CubeServer is not started." in cube-js/cube?

Ensure server.listen() completed successfully before calling close()

CubeServer is not started.

Error message

CubeServer is not started.

What it means

CubeServer.close() throws this when the underlying HTTP server instance is null, meaning the server was never started (or was already closed). close() checks this.server after closing the SQL server and aborts if there is nothing to stop. It guards against calling shutdown on a CubeServer that has not been initialized via listen().

Source

Thrown at packages/cubejs-server/src/server.ts:179

  }

  // @internal
  public async getDriver(ctx: DriverContext): Promise<BaseDriver> {
    return this.core.getDriver(ctx);
  }

  public async close() {
    try {
      if (this.socketServer) {
        await this.socketServer.close();
      }

      if (this.sqlServer) {
        await this.sqlServer.close();
      }

      if (!this.server) {
        throw new Error('CubeServer is not started.');
      }

      await util.promisify(this.server.close)();
      this.server = null;

      await this.core.releaseConnections();
    } catch (e: any) {
      if (this.core.event) {
        await this.core.event('Dev Server Fatal Error', {
          error: (e.stack || e.message || e).toString()
        });
      }

      throw e;
    }
  }

  /**

View on GitHub (pinned to 7d981676b3)

Solutions

Ensure server.listen() completed successfully before calling close()
Guard close() calls with a null check on the server or a boolean started flag
In shutdown handlers, track whether the server was started and skip close() otherwise
Wrap close() in try/catch and ignore this specific error in cleanup paths

Example fix

// before
const server = new CubeServer(options);
process.on('SIGTERM', () => server.close());

// after
const server = new CubeServer(options);
server.listen();
let started = false;
server.listen().then(() => { started = true; });
process.on('SIGTERM', () => { if (started) server.close(); });

Defensive patterns

Strategy: validation

Validate before calling

if (typeof server.close === 'function' && server['server']) {
  await server.close();
}

Type guard

function isStarted(server: CubeServer & { server?: unknown }): boolean {
  return (server as any).server != null;
}

Try / catch

try {
  await server.close();
} catch (e) {
  if (e.message !== 'CubeServer is not started.') throw e;
  // already stopped / never started: safe to ignore in cleanup
}

Prevention

Always call listen() before registering shutdown hooks that call close()
Use a single shutdown path guarded by a boolean/idempotent promise
In tests, use afterAll/afterEach teardown that tolerates a never-started server
Log whether the server started to make shutdown ordering visible

When it happens

Trigger: Calling server.close() before server.listen() was ever called, or calling close() twice — the first close sets this.server = null, so the second call hits the throw.

Common situations: Shutdown handlers (SIGTERM/SIGINT) that call close() unconditionally while the server failed to boot; test teardown calling close() on a server that never started due to an earlier error; double-invocation of graceful shutdown logic.

Related errors

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