{"record":{"id":"828728e389d0e8d4","repo":"vllm-project/vllm","slug":"ec-cpu-bytes-must-be-specified-in-ec-connector-ext","errorCode":null,"errorMessage":"ec_cpu_bytes must be specified in ec_connector_extra_config","messagePattern":"ec_cpu_bytes must be specified in ec_connector_extra_config","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/distributed/ec_transfer/ec_connector/cpu/common.py","lineNumber":81,"sourceCode":"    \"\"\"Build the EC mmap region from `vllm_config`.\n\n    Both `ECCPUScheduler` and `ECCPUWorker` call this to get the same\n    shared region (same engine_id, same block_size_bytes).\n    \"\"\"\n    ec_config = vllm_config.ec_transfer_config\n    assert ec_config is not None, \"ec_transfer_config required to build region\"\n\n    dp_rank = vllm_config.parallel_config.data_parallel_rank\n    engine_id = f\"{vllm_config.instance_id}_dp{dp_rank}\"\n\n    dtype = vllm_config.model_config.dtype\n    hidden_dim = _get_encoder_cache_hidden_dim(vllm_config)\n    element_size = torch.empty(0, dtype=dtype).element_size()\n    block_size_bytes = hidden_dim * element_size\n\n    cpu_bytes = ec_config.ec_connector_extra_config.get(\"ec_cpu_bytes\")\n    if not cpu_bytes:\n        raise ValueError(\"ec_cpu_bytes must be specified in ec_connector_extra_config\")\n    cpu_bytes = int(cpu_bytes)\n    num_blocks = cpu_bytes // block_size_bytes\n\n    return ECSharedRegion(\n        engine_id=engine_id,\n        num_blocks=num_blocks,\n        block_size_bytes=block_size_bytes,\n    )\n","sourceCodeStart":63,"sourceCodeEnd":90,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/ec_transfer/ec_connector/cpu/common.py#L63-L90","documentation":"The CPU encoder-cache shared region is sized in blocks derived from ec_cpu_bytes, which must be supplied through ec_connector_extra_config (a JSON-style extra config on ECTransferConfig). Without it the region cannot be dimensioned (num_blocks = ec_cpu_bytes // block_size_bytes), so build_region raises ValueError with the exact key name to set.","triggerScenarios":"Enabling the CPU EC connector but omitting \"ec_cpu_bytes\" in --ec-transfer-extra-config / ec_connector_extra_config; passing a falsy value like 0 or an empty string (the code checks `if not cpu_bytes`, so 0 also fails); typo in the key name.","commonSituations":"First-time setup of CPU-based encoder-cache transfer between producer and consumer vLLM instances; copying extra-config JSON from docs that omit this mandatory key; passing the value under a different key like cpu_bytes.","solutions":["Add ec_cpu_bytes to the extra config, sized as hidden_dim * dtype_size * desired_block_count (e.g. a few GiB for multimodal encoder caches)","Verify the key is exactly 'ec_cpu_bytes' and the value is a positive integer string","Cross-check against _get_encoder_cache_hidden_dim(vllm_config) * element_size to ensure num_blocks comes out > 0"],"exampleFix":"# before\nECTransferConfig(ec_connector=\"ECCPUConnector\", ec_connector_extra_config={})\n# ValueError: ec_cpu_bytes must be specified in ec_connector_extra_config\n\n# after\nECTransferConfig(\n    ec_connector=\"ECCPUConnector\",\n    ec_connector_extra_config={\"ec_cpu_bytes\": str(8 * 1024**3)},\n)","handlingStrategy":"validation","validationCode":"cfg = ec_transfer_config.ec_connector_extra_config\ncpu_bytes = int(cfg.get(\"ec_cpu_bytes\", 0))\nassert cpu_bytes > 0, \"set ec_connector_extra_config['ec_cpu_bytes'] (bytes)\"","typeGuard":"def ec_region_configured(ec_transfer_config) -> bool:\n    return bool(ec_transfer_config.ec_connector_extra_config.get(\"ec_cpu_bytes\"))","tryCatchPattern":null,"preventionTips":["Always pair the CPU EC connector with an explicit ec_cpu_bytes","Validate extra-config keys at startup, not at first region build","Size ec_cpu_bytes from hidden_dim * dtype_size * block count"],"tags":["configuration","ec-transfer","setup"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}