{"record":{"id":"5504b08df9bccc7b","repo":"facebookresearch/detectron2","slug":"total-batch-size-and-single-gpu-batch-size-are-mut","errorCode":null,"errorMessage":"total_batch_size and single_gpu_batch_size are mutually incompatible.\n                Please specify only one. ","messagePattern":"total_batch_size and single_gpu_batch_size are mutually incompatible\\.\n                Please specify only one\\. ","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"detectron2/data/build.py","lineNumber":333,"sourceCode":"    Args:\n        dataset (torch.utils.data.Dataset): a pytorch map-style or iterable dataset.\n        sampler (torch.utils.data.sampler.Sampler or None): a sampler that produces indices.\n            Must be provided iff. ``dataset`` is a map-style dataset.\n        total_batch_size, aspect_ratio_grouping, num_workers, collate_fn: see\n            :func:`build_detection_train_loader`.\n        single_gpu_batch_size: You can specify either `single_gpu_batch_size` or `total_batch_size`.\n            `single_gpu_batch_size` specifies the batch size that will be used for each gpu/process.\n            `total_batch_size` allows you to specify the total aggregate batch size across gpus.\n            It is an error to supply a value for both.\n        drop_last (bool): if ``True``, the dataloader will drop incomplete batches.\n\n    Returns:\n        iterable[list]. Length of each list is the batch size of the current\n            GPU. Each element in the list comes from the dataset.\n    \"\"\"\n    if single_gpu_batch_size:\n        if total_batch_size:\n            raise ValueError(\n                \"\"\"total_batch_size and single_gpu_batch_size are mutually incompatible.\n                Please specify only one. \"\"\"\n            )\n        batch_size = single_gpu_batch_size\n    else:\n        world_size = get_world_size()\n        assert (\n            total_batch_size > 0 and total_batch_size % world_size == 0\n        ), \"Total batch size ({}) must be divisible by the number of gpus ({}).\".format(\n            total_batch_size, world_size\n        )\n        batch_size = total_batch_size // world_size\n    logger = logging.getLogger(__name__)\n    logger.info(\"Making batched data loader with batch_size=%d\", batch_size)\n\n    if isinstance(dataset, torchdata.IterableDataset):\n        assert sampler is None, \"sampler must be None if dataset is IterableDataset\"\n    else:","sourceCodeStart":315,"sourceCodeEnd":351,"githubUrl":"https://github.com/facebookresearch/detectron2/blob/a2f4a8771ab77e8411c26b27f24f9489a28a2453/detectron2/data/build.py#L315-L351","documentation":"build_batch_data_loader takes either total_batch_size (split across all GPUs) or single_gpu_batch_size (per-GPU), never both. Supplying non-zero values for both raises this ValueError immediately.","triggerScenarios":"Calling build_batch_data_loader(dataset, sampler, batch_sampler/mapper, total_batch_size=16, single_gpu_batch_size=4); or a custom config that sets both dataloader values and reaches build_detection_train_loader's from_config.","commonSituations":"Upgrading detectron2 versions where new per-GPU batch size knobs were introduced alongside the old IMS_PER_BATCH; custom trainers setting cfg.DATALOADER fields plus passing explicit sizes.","solutions":["Keep only one argument: pass total_batch_size=cfg.SOLVER.IMS_PER_BATCH (default path) and drop single_gpu_batch_size","Or set single_gpu_batch_size only and clear total_batch_size","Audit custom build_detection_train_loader overrides after upgrading detectron2"],"exampleFix":"# before\nbuild_batch_data_loader(ds, mapper, sampler, total_batch_size=16, single_gpu_batch_size=4)\n# after\nbuild_batch_data_loader(ds, mapper, sampler, total_batch_size=16)","handlingStrategy":"validation","validationCode":"assert not (total_batch_size and single_gpu_batch_size), \"specify only one batch size arg\"","typeGuard":"def batch_args_valid(total=None, per_gpu=None) -> bool:\n    return not (total and per_gpu)","tryCatchPattern":null,"preventionTips":["Pass only cfg.SOLVER.IMS_PER_BATCH via the standard trainer path","Review dataloader construction after detectron2 upgrades","Wrap custom loader builders with an assertion on mutual exclusivity"],"tags":["dataloader","batch-size","detectron2","config"],"backgroundTag":"conflicting-config-options","analyzedSha":"a2f4a8771ab77e8411c26b27f24f9489a28a2453","analyzedAt":"2026-08-27T12:08:21.260Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}