{"record":{"id":"847fdf2702401ba0","repo":"cube-js/cube","slug":"expected-reference-to-the-model-in-format-ref-mod","errorCode":null,"errorMessage":"Expected reference to the model in format ref('model_name') but found '${metricDef.model}'","messagePattern":"Expected reference to the model in format ref\\('model_name'\\) but found '(.+?)'","errorType":"exception","errorClass":"UserError","httpStatus":null,"severity":"error","filePath":"packages/cubejs-dbt-schema-extension/src/Dbt.ts","lineNumber":152,"sourceCode":"\nexport class Dbt extends AbstractExtension {\n  public async loadMetricCubesFromDbtProject(projectPath: string, options: DbtLoadOptions): Promise<{ [cubeName: string]: any }> {\n    const dbtProjectPath = path.join(projectPath, 'dbt_project.yml');\n    if (!(await fs.pathExists(dbtProjectPath))) {\n      throw new UserError(`'${dbtProjectPath}' was not found. Please make sure '${projectPath}' is a path to the dbt project`);\n    }\n    // TODO read target path from dbt_project.yml\n    const manifestPath = path.join(projectPath, 'target', 'manifest.json');\n    if (!(await fs.pathExists(manifestPath))) {\n      throw new UserError(`'${manifestPath}' was not found. Please run 'dbt compile' in '${projectPath}'`);\n    }\n    const manifest = <DbtManifest>(await fs.readJSON(manifestPath));\n    Object.keys(manifest.metrics).forEach(metric => {\n      const regex = /^ref\\('(\\S+)'\\)$/;\n      const metricDef = manifest.metrics[metric];\n      const match = metricDef.model.match(regex);\n      if (!match) {\n        throw new UserError(`Expected reference to the model in format ref('model_name') but found '${metricDef.model}'`);\n      }\n      // eslint-disable-next-line prefer-destructuring\n      const modelName = match[1];\n      metricDef.model = modelName.indexOf('.') !== -1 ? modelName : `model.${metricDef.package_name}.${modelName}`;\n    });\n    return this.loadMetricCubesFromNormalizedManifest(manifest, manifestPath, options);\n  }\n\n  public async loadMetricCubesFromDbtCloud(jobId: string | number, authToken: string, options: DbtLoadOptions): Promise<{ [cubeName: string]: any }> {\n    const response = await fetch('https://metadata.cloud.getdbt.com/graphql', {\n      method: 'POST',\n      headers: {\n        'Content-Type': 'application/json',\n        Accept: 'application/json',\n        Authorization: `Bearer ${authToken}`\n      },\n      body: JSON.stringify({ query: loadModelsQuery, variables: { jobId } })\n    });","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/cube-js/cube/blob/7d981676b36392fec34088b9afab6bdcad40207c/packages/cubejs-dbt-schema-extension/src/Dbt.ts#L134-L170","documentation":"Each metric in the dbt manifest must reference its underlying model via a model string in the exact format ref('model_name'). loadMetricCubesFromDbtProject matches metricDef.model against the regex /^ref\\('(\\S+)'\\)$/ and throws this UserError when the string does not conform, since the model name cannot be extracted.","triggerScenarios":"A manifest metric's model field is e.g. 'model.my_project.my_model', a bare model name without ref(), uses double quotes ref(\"m\"), contains extra spaces, or was produced by tooling that writes resolved model references instead of the ref() syntax.","commonSituations":"Manually editing or programmatically post-processing manifest.json before Cube reads it; older/newer dbt versions writing a different model reference format; third-party tooling that rewrites manifests; copy-pasting metric definitions with the wrong model syntax.","solutions":["Fix the metric definition in the dbt project so model uses ref('model_name') syntax and re-run dbt compile","Check for quoting/whitespace issues: single quotes required inside ref(), no leading/trailing spaces","Regenerate manifest.json with the same dbt CLI version rather than hand-editing it","If tooling rewrites the manifest, ensure it preserves the ref('model_name') format"],"exampleFix":"// before (metric in manifest)\n\"model\": \"model.my_project.orders\"\n// after\n\"model\": \"ref('orders')\"","handlingStrategy":"validation","validationCode":"for (const m of Object.values(manifest.metrics)) {\n  if (!/^ref\\('(\\S+)'\\)$/.test(m.model)) {\n    throw new Error(`Metric ${m.name}: model must match ref('model_name'), got: ${m.model}`);\n  }\n}","typeGuard":"function hasRefModel(metricDef) {\n  return typeof metricDef.model === 'string' && /^ref\\('(\\S+)'\\)$/.test(metricDef.model);\n}","tryCatchPattern":"try {\n  await dbt.loadMetricCubesFromDbtProject(projectPath, opts);\n} catch (e) {\n  if (e.message.startsWith(\"Expected reference to the model\")) {\n    console.error('Fix metric model refs in dbt project and re-run dbt compile:', e.message);\n  } else { throw e; }\n}","preventionTips":["Always author metric model fields as ref('model_name') with single quotes","Do not hand-edit manifest.json; regenerate via dbt compile","Keep dbt CLI version consistent between environments","Add a schema lint on metric definitions in dbt CI"],"tags":["dbt","parsing","format-validation","manifest"],"backgroundTag":"schema-validation-failed","analyzedSha":"7d981676b36392fec34088b9afab6bdcad40207c","analyzedAt":"2026-09-02T03:45:10.400Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}