{"record":{"id":"b4f6409a049373c3","repo":"xai-org/x-algorithm","slug":"no-compiled-async-emb-binding-xrex-cuda-async-emb","errorCode":null,"errorMessage":"no compiled async_emb binding: xrex.cuda.async_emb.src has no async_emb_api extension on this box (compile src/ per the xrex/cuda/__init__.py build notes). use_async_emb requires the kernels.","messagePattern":"no compiled async_emb binding: xrex\\.cuda\\.async_emb\\.src has no async_emb_api extension on this box \\(compile src/ per the xrex/cuda/__init__\\.py build notes\\)\\. use_async_emb requires the kernels\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"critical","filePath":"phoenix/xrex/cuda/async_emb/async_emb.py","lineNumber":18,"sourceCode":"# SPDX-License-Identifier: Apache-2.0\n# Copyright 2026 X.AI Corp.\nimport math\nfrom typing import NamedTuple\n\nimport jax\nimport jax.numpy as jnp\nimport numpy as np\n\nfrom xrex.cuda.async_emb.comm_utils import (\n    get_context_id,\n    get_flatten_replica_groups,\n)\n\ntry:\n    from xrex.cuda.async_emb.src import async_emb_api\nexcept ImportError as e:\n    raise ImportError(\n        \"no compiled async_emb binding: xrex.cuda.async_emb.src has no \"\n        \"async_emb_api extension on this box (compile src/ per the \"\n        \"xrex/cuda/__init__.py build notes). use_async_emb requires the \"\n        \"kernels.\"\n    ) from e\n\ntry:\n    jax.ffi.register_ffi_target(\n        \"xrex_async_emb_lookup_start\",\n        fn={\n            \"initialize\": async_emb_api.lookup_start_init(),\n            \"execute\": async_emb_api.lookup_start(),\n        },\n        platform=\"CUDA\",\n    )\n    jax.ffi.register_ffi_target(\n        \"xrex_async_emb_lookup_done\", fn=async_emb_api.lookup_done(), platform=\"CUDA\"\n    )","sourceCodeStart":1,"sourceCodeEnd":36,"githubUrl":"https://github.com/xai-org/x-algorithm/blob/24c60942c5c5fdad3a6addffb4c6e6d2f228f04f/phoenix/xrex/cuda/async_emb/async_emb.py#L1-L36","documentation":"The async_emb Python bindings try to import the compiled C++/CUDA extension module async_emb_api from xrex.cuda.async_emb.src; the ImportError is re-raised with build instructions because the kernels only exist after compiling src/. use_async_emb=True is therefore only usable on boxes where the extension has been built and is importable.","triggerScenarios":"Importing xrex.cuda.async_emb.async_emb (directly or transitively by enabling use_async_emb in training config) on a machine where the src/ extension was never compiled, was built for a different Python env, or the .so is not on the path.","commonSituations":"Fresh clone / new container without the CUDA build step; switching virtualenvs or Python versions so the previously compiled extension no longer matches; running on a CPU-only box; CI image missing the compiled artifact.","solutions":["Compile the extension: follow the build notes in xrex/cuda/__init__.py (build src/ of xrex/cuda/async_emb, e.g. via the documented cmake/setup.py invocation) in the SAME Python environment you run with.","Reinstall/rebuild after any Python, CUDA toolkit, or JAX/XLA version change so the ABI matches.","If async embedding updates are not needed, set use_async_emb=False to avoid importing the kernels entirely.","Verify with: python -c \"from xrex.cuda.async_emb.src import async_emb_api; print(async_emb_api.__file__)\"."],"exampleFix":"# before (fails at import)\nfrom xrex.cuda.async_emb.async_emb import AsyncEmbContextHandle\n\n# after: build first, per xrex/cuda/__init__.py notes\n#   cd phoenix/xrex/cuda/async_emb/src && python setup.py install  (or the documented cmake build)\nfrom xrex.cuda.async_emb.async_emb import AsyncEmbContextHandle","handlingStrategy":"validation","validationCode":"def async_emb_available() -> bool:\n    try:\n        from xrex.cuda.async_emb.src import async_emb_api  # noqa: F401\n        return True\n    except ImportError:\n        return False\n\nif config.use_async_emb and not async_emb_available():\n    raise RuntimeError(\"compile xrex/cuda/async_emb/src first (see xrex/cuda/__init__.py)\")","typeGuard":null,"tryCatchPattern":"try:\n    from xrex.cuda.async_emb.async_emb import make_context_handle\nexcept ImportError as e:\n    logging.warning(\"async_emb kernels unavailable: %s; falling back to sync optimizer\", e)\n    config = config.replace(use_async_emb=False)","preventionTips":["Bake the src/ build step into the Dockerfile / setup hooks so the extension always exists.","Gate use_async_emb on the availability probe above so jobs fail with an actionable message instead of an import crash."],"tags":["cuda","import-error","native-extension","build-required","async-embedding"],"backgroundTag":"missing-compiled-native-extension","analyzedSha":"24c60942c5c5fdad3a6addffb4c6e6d2f228f04f","analyzedAt":"2026-08-28T11:40:14.686Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}