xai-org/x-algorithm · critical · ImportError

no compiled async_emb binding: xrex.cuda.async_emb.src has n

Error message

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.

What it means

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.

Source

Thrown at phoenix/xrex/cuda/async_emb/async_emb.py:18

# SPDX-License-Identifier: Apache-2.0
# Copyright 2026 X.AI Corp.
import math
from typing import NamedTuple

import jax
import jax.numpy as jnp
import numpy as np

from xrex.cuda.async_emb.comm_utils import (
    get_context_id,
    get_flatten_replica_groups,
)

try:
    from xrex.cuda.async_emb.src import async_emb_api
except ImportError as e:
    raise ImportError(
        "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."
    ) from e

try:
    jax.ffi.register_ffi_target(
        "xrex_async_emb_lookup_start",
        fn={
            "initialize": async_emb_api.lookup_start_init(),
            "execute": async_emb_api.lookup_start(),
        },
        platform="CUDA",
    )
    jax.ffi.register_ffi_target(
        "xrex_async_emb_lookup_done", fn=async_emb_api.lookup_done(), platform="CUDA"
    )

View on GitHub (pinned to 24c60942c5)

Solutions

  1. 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.
  2. Reinstall/rebuild after any Python, CUDA toolkit, or JAX/XLA version change so the ABI matches.
  3. If async embedding updates are not needed, set use_async_emb=False to avoid importing the kernels entirely.
  4. Verify with: python -c "from xrex.cuda.async_emb.src import async_emb_api; print(async_emb_api.__file__)".

Example fix

# before (fails at import)
from xrex.cuda.async_emb.async_emb import AsyncEmbContextHandle

# after: build first, per xrex/cuda/__init__.py notes
#   cd phoenix/xrex/cuda/async_emb/src && python setup.py install  (or the documented cmake build)
from xrex.cuda.async_emb.async_emb import AsyncEmbContextHandle
Defensive patterns

Strategy: validation

Validate before calling

def async_emb_available() -> bool:
    try:
        from xrex.cuda.async_emb.src import async_emb_api  # noqa: F401
        return True
    except ImportError:
        return False

if config.use_async_emb and not async_emb_available():
    raise RuntimeError("compile xrex/cuda/async_emb/src first (see xrex/cuda/__init__.py)")

Try / catch

try:
    from xrex.cuda.async_emb.async_emb import make_context_handle
except ImportError as e:
    logging.warning("async_emb kernels unavailable: %s; falling back to sync optimizer", e)
    config = config.replace(use_async_emb=False)

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of xai-org/x-algorithm@24c60942c5 (2026-08-28). Data as JSON: /api/errors/b4f6409a049373c3. Report an issue: GitHub.