Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CubejsServer
✓ import { CubejsServer } from '@cubejs-backend/server';
✗ const CubejsServer = require('cubejs-server');
The primary class for instantiating the Cube.js backend. Note the correct package name `@cubejs-backend/server`.
CubejsServerOptions
✓ import { CubejsServerOptions } from '@cubejs-backend/server';
TypeScript interface for configuring the Cube.js server instance.
generate
✓ import { generate } from '@cubejs-backend/server';
✗ import { CubejsServer } from '@cubejs-backend/server'; const { generate } = new CubejsServer();
Used for generating Cube.js schema files dynamically or programmatically. Often used in setup scripts.
This quickstart demonstrates how to set up and launch a basic Cube.js API server using Express. It shows essential configuration for database connection, API secret, port, and enabling the developer playground.
import express from 'express';
import { CubejsServer } from '@cubejs-backend/server';
import dotenv from 'dotenv';
import path from 'path';
dotenv.config({ path: path.resolve(process.cwd(), '.env') });
async function main() {
const server = new CubejsServer({
// Required for security and API token generation
// Use process.env.CUBEJS_API_SECRET ?? '' for production
apiSecret: process.env.CUBEJS_API_SECRET ?? 'YOUR_API_SECRET',
// Configure your database connection
dbType: process.env.CUBEJS_DB_TYPE ?? 'postgres',
dbHost: process.env.CUBEJS_DB_HOST ?? 'localhost',
dbName: process.env.CUBEJS_DB_NAME ?? 'cubejs_data',
dbUser: process.env.CUBEJS_DB_USER ?? 'cubejs_user',
dbPass: process.env.CUBEJS_DB_PASS ?? 'cubejs_password',
// Path to your Cube.js schema files (e.g., .js, .yml)
// Defaults to 'schema' folder in the root
// schemaPath: path.resolve(process.cwd(), 'schema'),
// Port for the Cube.js API
port: parseInt(process.env.PORT ?? '4000', 10),
// Enable developer playground in development mode
devPlayground: process.env.NODE_ENV === 'development',
// Additional server configuration options
// full stack traces for development debugging
extendContext: (req) => ({
traceId: req.headers['x-request-id'] || 'no-trace',
}),
});
const app = express();
// Integrate Cube.js with your Express app
await server.initApp(app);
app.listen(server.options.port, () => {
console.log(`🚀 Cube.js server is running on http://localhost:${server.options.port}`);
if (server.options.devPlayground) {
console.log(`▶️ Cube.js Playground available at http://localhost:${server.options.port}`);
}
});
}
main().catch((e) => {
console.error('Failed to start Cube.js server:', e);
process.exit(1);
});
cubejs --version
Debug
Known issues
breakingThe package name for the Cube.js server was changed from `cubejs-server` (deprecated) to `@cubejs-backend/server`. Using the old package name will result in an outdated, unmaintained version and potential compatibility issues. Ensure all dependencies and imports reflect `@cubejs-backend/server`.fixUpdate `package.json` to use `@cubejs-backend/server` and modify all import statements to `from '@cubejs-backend/server'`.
affects: <=0.32.0 (for old package name), >=0.33.0 (for new package name)
gotchaDatabase drivers (e.g., `pg`, `mysql2`, `mongodb`, `clickhouse`) are peer dependencies of Cube.js. You must explicitly install the correct driver package for your specific database(s) alongside `@cubejs-backend/server`.fixRun `npm install <your-db-driver-package>` (e.g., `npm install pg`) or `yarn add <your-db-driver-package>`.
affects: >=0.1.0
breakingCube.js `0.x.x` versions, while actively developed, may introduce breaking changes in minor releases. Always consult the release notes and changelog before upgrading, especially regarding schema definitions, configuration formats (e.g., from `cube.js` to `cube.config.js` or `.env` for database credentials), and API scopes.fixReview the official Cube.js changelog for your specific version range and adapt your code and configuration files (`.env`, `schema/`, `cube.config.js`) accordingly.
affects: >=0.1.0
breakingNode.js version support has evolved. Node.js v12 and v15 support was dropped with v0.32.0, and v14 was deprecated shortly after. Newer versions prioritize Node.js v16 and above. Using unsupported Node.js versions can lead to unexpected errors or stability issues.fixUpgrade your Node.js environment to a supported LTS version (e.g., Node.js 16, 18, or 20, as recommended by Cube.js documentation). Update your `engines` field in `package.json`.
affects: >=0.32.0
deprecatedEmbedding Cube.js directly into existing Express applications using `initApp(app)` has been deprecated in favor of deploying Cube.js as a separate microservice. While still functional, this pattern is less performant and reliable for production deployments, especially as Cube.js evolves towards Rust-based components.fixConsider deploying Cube.js as a standalone service (e.g., via Docker) and connecting to it from your main application via its API. Explore Cube Cloud for managed deployments.
affects: >=0.24.0
Errors
Common errors & fixes
Error: Cannot find module 'pg'
The required database driver for PostgreSQL is not installed. This applies to any database type (e.g., `mysql2` for MySQL).
fixInstall the necessary database driver: `npm install pg` (for PostgreSQL) or `yarn add pg`.
Error: Data source is not configured. Please check your CUBEJS_DB_* environment variables.
Cube.js cannot connect to the database because environment variables (like `CUBEJS_DB_TYPE`, `CUBEJS_DB_HOST`, `CUBEJS_DB_NAME`, etc.) are either missing or incorrect, or the `.env` file is not loaded.
fixEnsure that your `.env` file exists and contains all necessary `CUBEJS_DB_*` variables for your database, and that `dotenv.config()` is called correctly at the start of your application. Verify database credentials and host accessibility.
Error: 'CUBEJS_API_SECRET' is not set. It is required to secure your API. Please set it via environment variable or in Cube.js options.
The `CUBEJS_API_SECRET` environment variable or the `apiSecret` option in `CubejsServer` constructor is not provided. This secret is crucial for securing your Cube.js API.
fixSet `CUBEJS_API_SECRET` in your `.env` file (e.g., `CUBEJS_API_SECRET=YOUR_SECURE_SECRET`) or pass it directly in the `CubejsServer` constructor options. Ensure it's a strong, unique secret for production.
thread 'main' panicked at 'called `Option::unwrap()` on a `None` value'
This low-level error often indicates a corrupted Cube Store metastore, especially when using Cube Store as the caching/queue engine, typically due to improper shutdown.
fixTry deleting the `.cubestore` directory in your project root to clear the corrupted metastore. Note that this will clear your cache and pre-aggregations, which will be rebuilt on restart.
Audit
Dependencies
@cubejs-backend/schema-compilerrequiredRequired for processing Cube.js data schema files.
@cubejs-backend/query-orchestratorrequiredCore component for query execution, caching, and scheduling.
pgoptionalPostgreSQL database driver. Install the appropriate driver for your data source (e.g., `mysql2`, `mongodb`, `clickhouse`).
expressrequiredUsed internally for handling API routes and middleware. Often a direct or transitive dependency.
body-parserrequiredUsed by Express for parsing request bodies.
corsrequiredExpress middleware for enabling Cross-Origin Resource Sharing.