sgl-project/sglang · error · ValueError

mapping [{offset}, {offset + size}) is outside reservation [

Error message

mapping [{offset}, {offset + size}) is outside reservation [0, {self.size})

What it means

VmmReservation.map validates that [offset, offset+size) lies fully inside the reserved virtual range [0, self.size); any out-of-range mapping request is rejected because the CUDA driver can only map physical pages into an existing VA reservation.

Source

Thrown at python/sglang/srt/utils/cuda_vmm_utils.py:542

                "cuMemAddressReserve(local)",
            )
        )
        self._mappings = []
        self._closed = False

    def map(
        self,
        offset: int,
        size: int,
        *,
        retain_handle: bool,
    ):
        """Create and map local memory at ``base + offset``."""
        if self._closed:
            raise RuntimeError("VmmReservation.map after close")
        offset, size = int(offset), int(size)
        if offset < 0 or size <= 0 or offset + size > self.size:
            raise ValueError(
                f"mapping [{offset}, {offset + size}) is outside reservation "
                f"[0, {self.size})"
            )

        drv = _get_cuda_driver()
        address = self.base + offset
        handle = check_drv(drv.cuMemCreate(size, self._prop, 0), "cuMemCreate(local)")
        mapped = False
        try:
            check_drv(
                drv.cuMemMap(address, size, 0, handle, 0),
                "cuMemMap(local)",
            )
            mapped = True
            check_drv(
                drv.cuMemSetAccess(
                    address,
                    size,

View on GitHub (pinned to 0132848349)

Solutions

1. Verify the reservation size at creation and assert offset + size <= reservation.size before mapping.
2. Check unit consistency: ensure offsets/sizes are bytes, not elements/pages.
3. Round sizes up to the mapping granularity and re-check against reservation size.

Example fix

// before
res.map(offset=chunk_idx * chunk_elems, size=chunk_elems)

// after
off = chunk_idx * chunk_bytes
assert off + chunk_bytes <= res.size, f"{off}+{chunk_bytes} > {res.size}"
res.map(offset=off, size=chunk_bytes)

def check_map(res, offset, size):
    assert 0 <= offset and size > 0 and offset + size <= res.size, \
        f"map [{offset},{offset+size}) outside [0,{res.size})"

try:
    res.map(offset, size)
except ValueError:
    # recompute offsets from res.size and retry once
    raise

When it happens

Trigger: Calling VmmReservation.map(offset, size) with negative offset, size <= 0, or offset + size > self.size (the reservation's total byte size).

Common situations: Size math bugs when computing chunk offsets (e.g. using element count instead of bytes), assuming a bigger reservation than was created, or off-by-one page rounding when aligning offsets to 2MB granularity.

Related errors

• memory_size must be positive
• consumer_count must be positive
• recycle_interval must be positive
• consumer_count must be 1, the attention TP size, or the full
• CUDA VMM feature transport requires each feature field to co

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/69da0d563d207315. Report an issue: GitHub.