{"record":{"id":"73c0309d85bd8d15","repo":"xai-org/x-algorithm","slug":"expected-2d-emb-table-got-shape-embeddings-shape","errorCode":null,"errorMessage":"Expected 2D emb_table, got shape={embeddings.shape}","messagePattern":"Expected 2D emb_table, got shape=(.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"phoenix/xrex/inference/h2d.py","lineNumber":396,"sourceCode":"        candidate_multimodal_embeddings_gpu = mm_2d.reshape(\n            total_batch, mm_cand_seq, mm_buf.embedding_dim\n        )\n\n    return merged_device, candidate_multimodal_embeddings_gpu\n\n\ndef _maybe_init_rows(\n    embeddings: npt.NDArray,\n    row_indexes: npt.NDArray[np.uint32],\n) -> None:\n    logger.info(\n        \"Lazy init emb_table rows: unique_rows=%d shape=%s dtype=%s\",\n        len(np.unique(row_indexes)),\n        embeddings.shape,\n        embeddings.dtype,\n    )\n    if embeddings.ndim != 2:\n        raise ValueError(f\"Expected 2D emb_table, got shape={embeddings.shape}\")\n    row_size = embeddings.shape[1]\n    scale = 1.0 / math.sqrt(row_size)\n    unique_rows = np.unique(row_indexes)\n    for row in unique_rows:\n        idx = int(row)\n        first = int(embeddings[idx, 0])\n        if first != 0:\n            continue\n        rng = np.random.default_rng(idx)\n        values = rng.uniform(-scale, scale, size=row_size).astype(np.float32)\n        if embeddings.dtype == np.uint16:\n            embeddings[idx] = (values.view(np.uint32) >> 16).astype(np.uint16)\n        elif embeddings.dtype == np.uint32:\n            embeddings[idx] = values.view(np.uint32)\n        else:\n            raise ValueError(f\"Unsupported emb_table dtype: {embeddings.dtype}\")\n","sourceCodeStart":378,"sourceCodeEnd":413,"githubUrl":"https://github.com/xai-org/x-algorithm/blob/24c60942c5c5fdad3a6addffb4c6e6d2f228f04f/phoenix/xrex/inference/h2d.py#L378-L413","documentation":"Raised by _maybe_init_rows during lazy initialization of embedding table rows. The function expects the emb_table to be a 2D array of shape [num_rows, row_size] so it can index embeddings[idx, 0] and fill whole rows; if the array is 1D or 3D+, shape[1] is not the row width and row writes would be wrong, so it fails fast. It surfaces through lookup_h2d_embeddings when the passed emb_table has the wrong rank.","triggerScenarios":"Calling lookup_h2d_embeddings with an embeddings array that is 1D (a single flattened row), 3D (e.g. [vocab, seq, dim] not squeezed), or a 0-d array; also when a checkpoint loader reshapes the table incorrectly before lookup.","commonSituations":"Loading a raw flattened embedding blob from a checkpoint and passing it without reshape; passing per-sequence embeddings (batch of 2D tables) instead of the vocab table; test fixtures constructing np.zeros(vocab*dim) instead of (vocab, dim).","solutions":["Reshape the table to 2D before lookup: embeddings.reshape(num_rows, row_size) with the correct vocab and dim from the config","If you intended per-item embeddings, slice out the actual table (e.g. batch[0]) rather than passing the stacked array","Verify the checkpoint field you loaded is the emb_table itself and not a flattened byte buffer"],"exampleFix":"# before\ntable = np.frombuffer(blob, dtype=np.uint16)  # 1D\nrows = lookup_h2d_embeddings(idx, table, ...)\n# after\ntable = np.frombuffer(blob, dtype=np.uint16).reshape(vocab, dim)\nrows = lookup_h2d_embeddings(idx, table, ...)","handlingStrategy":"validation","validationCode":"assert isinstance(embeddings, np.ndarray) and embeddings.ndim == 2, (\n    f\"emb_table must be 2D, got {embeddings.shape}\")","typeGuard":"def is_2d_table(a: np.ndarray) -> bool:\n    return isinstance(a, np.ndarray) and a.ndim == 2","tryCatchPattern":"try:\n    rows = lookup_h2d_embeddings(idx, table, ...)\nexcept ValueError as e:\n    if \"Expected 2D\" in str(e):\n        table = table.reshape(vocab, dim)\n    else:\n        raise","preventionTips":["Always construct tables with explicit (vocab, dim) shape","Add ndim assertions in checkpoint loaders, not just at lookup time"],"tags":["shape","embedding","numpy","validation"],"backgroundTag":"array-shape-mismatch","analyzedSha":"24c60942c5c5fdad3a6addffb4c6e6d2f228f04f","analyzedAt":"2026-08-28T11:40:14.686Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}