{"record":{"id":"cddccdc84d7d410d","repo":"cube-js/cube","slug":"the-keybydatasource-cubejs-db-name-datasource","errorCode":null,"errorMessage":"The ${keyByDataSource('CUBEJS_DB_NAME', dataSource)} is required and missing.","messagePattern":"The (.+?) is required and missing\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/cubejs-backend-shared/src/env.ts","lineNumber":578,"sourceCode":"  }: DataSourceOpts) => (\n    get(keyByDataSource('CUBEJS_DB_PASS', dataSource, preAggregations)).asString()\n  ),\n\n  /**\n   * Database name.\n   */\n  dbName: ({\n    required,\n    dataSource,\n    preAggregations,\n  }: {\n    dataSource: string,\n    required?: boolean,\n    preAggregations?: boolean,\n  }) => {\n    const val = get(keyByDataSource('CUBEJS_DB_NAME', dataSource, preAggregations)).asString();\n    if (required && !val) {\n      throw new Error(\n        `The ${\n          keyByDataSource('CUBEJS_DB_NAME', dataSource)\n        } is required and missing.`\n      );\n    }\n    return val;\n  },\n\n  /**\n   * Database name.\n   * @deprecated\n   */\n  dbSchema: ({\n    required,\n    dataSource,\n    preAggregations,\n  }: {\n    dataSource: string,","sourceCodeStart":560,"sourceCodeEnd":596,"githubUrl":"https://github.com/cube-js/cube/blob/7d981676b36392fec34088b9afab6bdcad40207c/packages/cubejs-backend-shared/src/env.ts#L560-L596","documentation":"cubejsDbName reads CUBEJS_DB_NAME (per data source) and throws when a caller marks it required via the { required: true } option but the variable is unset or empty. The error names the resolved data-source-specific variable, e.g. CUBEJS_DS_MYSQL_DB_NAME.","triggerScenarios":"Calling getEnv('dbName') or the db-name accessor with required: true while neither CUBEJS_DB_NAME nor CUBEJS_DS_<DATASOURCE>_DB_NAME is set in the environment for that data source.","commonSituations":"Deploying without copying the full .env; Kubernetes secret not mounted; using only a DS-specific name while the code checks the generic one for a dataSource whose prefix differs; renaming databases during migrations.","solutions":["Set CUBEJS_DB_NAME (or CUBEJS_DS_<DATASOURCE>_DB_NAME) in the environment before startup.","Verify which data source name is being passed to the accessor matches the prefix in your env vars (case-sensitive toUpperCase).","Check that your secret/config map is actually mounted and loaded (docker exec / kubectl exec and echo the var).","If the database name is supplied by driver config instead of env, drop required: true."],"exampleFix":"// before (deployment)\n# CUBEJS_DB_NAME missing\n// after\ndocker run -e CUBEJS_DB_NAME=analytics ...","handlingStrategy":"try-catch","validationCode":"const dsKey = `CUBEJS_DS_${dataSource.toUpperCase()}_DB_NAME`;\nif (!process.env[dsKey] && !process.env.CUBEJS_DB_NAME)\n  throw new Error(`Missing ${dsKey} (or CUBEJS_DB_NAME) for data source ${dataSource}`);","typeGuard":null,"tryCatchPattern":"try {\n  const dbName = getEnv('dbName', { dataSource, required: true });\n} catch (e) {\n  if (String(e.message).includes('DB_NAME') && e.message.includes('required and missing')) {\n    console.error(`Provide ${keyByDataSource('CUBEJS_DB_NAME', dataSource)} in the environment`);\n    process.exit(1);\n  }\n  throw e;\n}","preventionTips":["Verify required env vars at process startup with a fail-fast checklist.","Ensure Kubernetes secrets / .env files are actually mounted in the container.","Match the dataSource string in code with the env prefix (case-insensitively uppercased).","Use the CUBEJS_DB_NAME name, not the deprecated variants."],"tags":["configuration","environment-variables","missing-var","database"],"backgroundTag":"missing-env-var","analyzedSha":"7d981676b36392fec34088b9afab6bdcad40207c","analyzedAt":"2026-09-02T03:45:10.400Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}