{"record":{"id":"353c5d10fe3c2301","repo":"ruvnet/ruflo","slug":"expected-this-dimensions-x-this-dimensions-mat","errorCode":null,"errorMessage":"Expected ${this.dimensions}x${this.dimensions} matrix","messagePattern":"Expected (.+?)x(.+?) matrix","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/plugins/src/integrations/ruvector/quantization.ts","lineNumber":1278,"sourceCode":"    const rotatedQuery = this.rotationMatrix\n      ? matVec(this.rotationMatrix, query)\n      : query;\n    return super.computeDistances(rotatedQuery, codes);\n  }\n\n  /**\n   * Gets the rotation matrix.\n   */\n  getRotationMatrix(): number[][] | null {\n    return this.rotationMatrix ? this.rotationMatrix.map(r => [...r]) : null;\n  }\n\n  /**\n   * Sets the rotation matrix directly.\n   */\n  setRotationMatrix(matrix: number[][]): void {\n    if (matrix.length !== this.dimensions || matrix[0].length !== this.dimensions) {\n      throw new Error(`Expected ${this.dimensions}x${this.dimensions} matrix`);\n    }\n    this.rotationMatrix = matrix.map(r => [...r]);\n  }\n}\n\n// ============================================================================\n// SQL Integration\n// ============================================================================\n\n/**\n * QuantizationSQL generates SQL for quantized vector operations.\n *\n * Provides SQL statements for:\n * - Creating quantized storage tables\n * - Inserting quantized vectors\n * - Searching with quantized distances\n */\nexport class QuantizationSQL {","sourceCodeStart":1260,"sourceCodeEnd":1296,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/plugins/src/integrations/ruvector/quantization.ts#L1260-L1296","documentation":"Thrown by OptimizedProductQuantizer.setRotationMatrix() when the supplied matrix is not exactly dimensions x dimensions. The rotation (Hadamard-like) matrix must be square and match the vector dimensionality because encoding applies it to full input vectors. A wrong-shape matrix means the loaded OPQ state does not correspond to this quantizer's configuration.","triggerScenarios":"Loading a rotation matrix trained for a different embedding dimension (e.g. 384 vs 768) into the current quantizer; passing a transposed or ragged (uneven row lengths) matrix; hand-editing serialized JSON and dropping a row.","commonSituations":"Switching embedding models without retraining the OPQ space; artifacts from a staging dimension reused in production; JSON round-trips that silently truncate rows.","solutions":["Retrain OPQ with the current dimensions and persist the new rotation matrix together with the codebooks","Load artifacts only into an OptimizedProductQuantizer constructed with the dimensions the artifact was trained for (store dimensions in the artifact metadata)","Validate matrix.length and every matrix[i].length === dimensions before calling setRotationMatrix"],"exampleFix":"// before\nconst opq = new OptimizedProductQuantizer({ dimensions: 768, /* ... */ });\nopq.setRotationMatrix(savedFrom384Model.rotationMatrix); // throws\n\n// after\nconst opq = new OptimizedProductQuantizer({ dimensions: saved.dimensions, /* ... */ });\nopq.setRotationMatrix(saved.rotationMatrix);","handlingStrategy":"validation","validationCode":"const isSquare =\n  matrix.length === dims && matrix.every(row => row.length === dims);\nif (!isSquare) {\n  throw new Error(`Rotation matrix must be ${dims}x${dims}`);\n}\nopq.setRotationMatrix(matrix);","typeGuard":"const isRotationMatrix = (m: unknown, dims: number): m is number[][] =>\n  Array.isArray(m) &&\n  m.length === dims &&\n  (m as number[][]).every(r => Array.isArray(r) && r.length === dims &&\n    r.every(Number.isFinite));","tryCatchPattern":"try {\n  opq.setRotationMatrix(matrix);\n} catch (err) {\n  if (err instanceof Error && err.message.includes('x')) { // shape message\n    throw new Error(`OPQ artifact dimension mismatch: ${err.message} — retrain for dims=${opq.dimensions}`);\n  }\n  throw err;\n}","preventionTips":["Store the training dimensions in the OPQ artifact next to the rotation matrix","Retrain OPQ whenever the embedding model (and therefore dimensions) changes","Validate serialized JSON matrix shape before loading, since JSON round-trips can silently alter structure"],"tags":["quantization","opq","dimension-mismatch","deserialization"],"backgroundTag":"dimension-mismatch","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","contentChangedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}