{"record":{"id":"c0f2584bce984065","repo":"xai-org/x-algorithm","slug":"use-async-emb-requires-an-embedding-optimizer-impl","errorCode":null,"errorMessage":"use_async_emb requires an embedding optimizer implementing AsyncEmbOptimizer, and {type(self).__name__} has no fused table update","messagePattern":"use_async_emb requires an embedding optimizer implementing AsyncEmbOptimizer, and (.+?) has no fused table update","errorType":"validation","errorClass":"NotImplementedError","httpStatus":null,"severity":"critical","filePath":"phoenix/xrex/optimizers/recsys/async_emb_gradient_update.py","lineNumber":32,"sourceCode":"\nclass AsyncEmbGradientUpdate(NamedTuple):\n    unique_tokens: jax.Array\n    grads: jax.Array\n    segment_ids: jax.Array\n    pending: jax.Array\n\n\n@runtime_checkable\nclass AsyncEmbOptimizer(Protocol):\n    def gradient_update_start(\n        self,\n        context: async_emb.AsyncEmbContextHandle,\n        update: AsyncEmbGradientUpdate,\n        table: jax.Array,\n        state: Any,\n        gate: jax.Array,\n    ) -> tuple[tuple[jax.Array, ...], jax.Array, Any, dict[str, jax.Array]]:\n        raise NotImplementedError(\n            f\"use_async_emb requires an embedding optimizer implementing \"\n            f\"AsyncEmbOptimizer, and {type(self).__name__} has no fused table update\"\n        )\n\n    def gradient_update_done(\n        self, context: async_emb.AsyncEmbContextHandle, gate: jax.Array\n    ) -> tuple[jax.Array, jax.Array, jax.Array]:\n        raise NotImplementedError(\n            f\"use_async_emb requires an embedding optimizer implementing \"\n            f\"AsyncEmbOptimizer, and {type(self).__name__} has no fused table update\"\n        )\n","sourceCodeStart":14,"sourceCodeEnd":44,"githubUrl":"https://github.com/xai-org/x-algorithm/blob/24c60942c5c5fdad3a6addffb4c6e6d2f228f04f/phoenix/xrex/optimizers/recsys/async_emb_gradient_update.py#L14-L44","documentation":"When use_async_emb is enabled, the trainer calls gradient_update_start on the embedding optimizer to perform a fused embedding-table update. The default implementation raises NotImplementedError, so any optimizer class that does not implement AsyncEmbOptimizer's fused update fails here, with the class name embedded in the message.","triggerScenarios":"Enabling use_async_emb in the recsys training config while using a plain optimizer (e.g. the standard Adam wrapper) for the embedding tables; instantiating AsyncEmbGradientUpdate and calling gradient_update_start on a subclass that only overrides gradient_update_done.","commonSituations":"Turning on the async embedding update feature of xrex without swapping the embedding optimizer for an AsyncEmbOptimizer implementation; upgrading where the async-emb API gained new required methods.","solutions":["Use an optimizer class that implements AsyncEmbOptimizer (fused table update) for the embeddings when use_async_emb=True","Subclass and implement gradient_update_start (and gradient_update_done) on your optimizer","Disable use_async_emb if fused async embedding updates are not needed"],"exampleFix":"# before\ncfg = TrainConfig(use_async_emb=True)  # optimizer = default Adam\n# after\ncfg = TrainConfig(use_async_emb=False)\n# or: optimizer = AsyncEmbAdam(...)  # implements AsyncEmbOptimizer","handlingStrategy":"type-guard","validationCode":"from phoenix.xrex.optimizers.recsys import async_emb\nif cfg.use_async_emb:\n    assert isinstance(emb_opt, async_emb.AsyncEmbOptimizer)","typeGuard":"def supports_async_emb(opt) -> bool:\n    return (hasattr(opt, 'gradient_update_start')\n            and type(opt).gradient_update_start is not AsyncEmbGradientUpdate.gradient_update_start)","tryCatchPattern":"try:\n    upd = emb_opt.gradient_update_start(ctx, update, table, state, gate)\nexcept NotImplementedError:\n    raise ConfigError('use_async_emb=True requires an AsyncEmbOptimizer') from None","preventionTips":["Gate use_async_emb on an isinstance check in config validation","Keep a registry of async-emb-capable optimizers"],"tags":["async-embedding","optimizer","recsys","not-implemented","jax"],"backgroundTag":"missing-interface-implementation","analyzedSha":"24c60942c5c5fdad3a6addffb4c6e6d2f228f04f","analyzedAt":"2026-08-28T11:40:14.686Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}