{"record":{"id":"4b900e66aaf001e2","repo":"cube-js/cube","slug":"context-must-be-a-single-reference-not-an-arra","errorCode":null,"errorMessage":"${context} must be a single reference, not an array","messagePattern":"(.+?) must be a single reference, not an array","errorType":"validation","errorClass":"UserError","httpStatus":null,"severity":"error","filePath":"packages/cubejs-schema-compiler/src/compiler/CubeSymbols.ts","lineNumber":1247,"sourceCode":"      // For any branch of return type that can can contain just an object it's OK to return string\n      return arrayOrSingle.toString() as any;\n    }\n\n    const references: Array<string> = arrayOrSingle.map(p => p.toString());\n    // arrayOrSingle is of type `T`, and we just checked that it is an array\n    // Which means that both `T` and result must be arrays\n    // For any branch of return type that can contain array it's OK to return array\n    return options.originalSorting ? references : R.sortBy(R.identity, references) as any;\n  }\n\n  public evaluateReference(\n    cube: string,\n    referencesFn: (...args: Array<unknown>) => ToString,\n    context: string\n  ): string {\n    const result = this.evaluateReferences(cube, referencesFn);\n    if (Array.isArray(result)) {\n      throw new UserError(`${context} must be a single reference, not an array`);\n    }\n\n    return result;\n  }\n\n  public pathFromArray(array: string[]): string {\n    return array.join('.');\n  }\n\n  /**\n   * Split join path to member to join hint and member path: `A.B.C.D.E.dim` => `[A, B, C, D, E]` + `E.dim`\n   */\n  public static joinHintFromPath(path: string): { path: string, joinHint: string[] } {\n    const parts = path.split('.');\n    if (parts.length > 2) {\n      // Path contains join path\n      const joinHint = parts.slice(0, -1);\n      return {","sourceCodeStart":1229,"sourceCodeEnd":1265,"githubUrl":"https://github.com/cube-js/cube/blob/7d981676b36392fec34088b9afab6bdcad40207c/packages/cubejs-schema-compiler/src/compiler/CubeSymbols.ts#L1229-L1265","documentation":"CubeSymbols evaluates a function that must return a single member reference (a string) during schema compilation. If the function returns an array instead, the compiler cannot use it where a lone reference is required, so it throws this UserError. It guards APIs like join paths or reference getters that expect exactly one dimension/measure name.","triggerScenarios":"A schema function passed to CubeSymbols (e.g. a references function, join SQL, or referencesFn returning a member name) returns an array of strings instead of a single string. E.g. a join definition whose SQL or referenced member resolves to `[...]`.","commonSituations":"Defining a join with `references: (a, b) => [a.id, b.id]` style multi-value return where a single reference is expected; copying an array variable into a context expecting one member name; TypeScript-less JS schemas where the wrong shape slips through.","solutions":["Change the function to return a single string reference instead of an array (e.g. `return a.id` not `[a.id]`).","If you need multiple references, move them to the correct multi-value API (e.g. the member list side of the join definition).","Check the data model docs for the exact expected signature of the option you are passing."],"exampleFix":"// before\njoins: {\n  Users: { sql: '\\${CUBE}.userId = \\${Users.id}', references: (a, b) => [a.userId, b.id] }\n}\n// after\njoins: {\n  Users: { sql: '\\${CUBE}.userId = \\${Users.id}', references: (a, b) => [a.userId, b.id] } // keep arrays in references;\n  // for single-reference APIs: (a) => a.userId\n}","handlingStrategy":"validation","validationCode":"const refs = myReferencesFn(cubeA, cubeB);\nif (Array.isArray(refs)) {\n  throw new Error('referencesFn must return a single string reference, got array');\n}","typeGuard":"function isSingleReference(v) { return typeof v === 'string'; }","tryCatchPattern":"try { await compiler.compile(); } catch (e) { if (e instanceof UserError && /must be a single reference, not an array/.test(e.message)) { /* fix schema fn */ } else throw e; }","preventionTips":["Type reference-returning functions as returning string, not string[]","Keep arrays only in options documented as multi-value (e.g. join references lists)","Run schema compilation in CI to catch shape mistakes early"],"tags":["schema-compiler","user-input","data-modeling"],"backgroundTag":"unexpected-array-reference","analyzedSha":"7d981676b36392fec34088b9afab6bdcad40207c","analyzedAt":"2026-09-02T03:45:10.400Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}