facebookresearch/detectron2 · error · ValueError

Unknown training sampler: {}

Error message

Unknown training sampler: {}

What it means

The training dataloader's from_config reads cfg.DATALOADER.SAMPLER_NAME and supports a fixed set ('TrainingSampler', 'RandomSubsetTrainingSampler', 'WeightedTrainingSampler', 'WeightedCategoryTrainingSampler', 'RepeatFactorTrainingSampler' depending on version). Any other string raises this ValueError.

Source

Thrown at detectron2/data/build.py:508

        else:
            logger.info("Using training sampler {}".format(sampler_name))
            if sampler_name == "TrainingSampler":
                sampler = TrainingSampler(len(dataset), seed=cfg.SEED)
            elif sampler_name == "RepeatFactorTrainingSampler":
                repeat_factors = RepeatFactorTrainingSampler.repeat_factors_from_category_frequency(
                    dataset, cfg.DATALOADER.REPEAT_THRESHOLD, sqrt=cfg.DATALOADER.REPEAT_SQRT
                )
                sampler = RepeatFactorTrainingSampler(repeat_factors, seed=cfg.SEED)
            elif sampler_name == "RandomSubsetTrainingSampler":
                sampler = RandomSubsetTrainingSampler(
                    len(dataset), cfg.DATALOADER.RANDOM_SUBSET_RATIO
                )
            elif sampler_name == "WeightedTrainingSampler":
                sampler = _build_weighted_sampler(cfg)
            elif sampler_name == "WeightedCategoryTrainingSampler":
                sampler = _build_weighted_sampler(cfg, enable_category_balance=True)
            else:
                raise ValueError("Unknown training sampler: {}".format(sampler_name))

    return {
        "dataset": dataset,
        "sampler": sampler,
        "mapper": mapper,
        "total_batch_size": cfg.SOLVER.IMS_PER_BATCH,
        "aspect_ratio_grouping": cfg.DATALOADER.ASPECT_RATIO_GROUPING,
        "num_workers": cfg.DATALOADER.NUM_WORKERS,
    }


@configurable(from_config=_train_loader_from_config)
def build_detection_train_loader(
    dataset,
    *,
    mapper,
    sampler=None,
    total_batch_size,

View on GitHub (pinned to a2f4a8771a)

Solutions

1. Fix the name to one of the supported values (check the elif chain in detectron2/data/build.py)
2. For custom sampling, implement a custom build_detection_train_loader that constructs your sampler directly
3. Copy exact spelling from detectron2/config/defaults.py DATALOADER.SAMPLER_NAME docs in your version

Example fix

# before
cfg.DATALOADER.SAMPLER_NAME = "trainingsampler"
# after
cfg.DATALOADER.SAMPLER_NAME = "TrainingSampler"

known = {"TrainingSampler", "RandomSubsetTrainingSampler", "RepeatFactorTrainingSampler", "WeightedTrainingSampler", "WeightedCategoryTrainingSampler"}
assert cfg.DATALOADER.SAMPLER_NAME in known, f"unknown sampler {cfg.DATALOADER.SAMPLER_NAME}"

def is_known_sampler(name: str) -> bool:
    return name in {"TrainingSampler", "RandomSubsetTrainingSampler", "RepeatFactorTrainingSampler", "WeightedTrainingSampler", "WeightedCategoryTrainingSampler"}

try:
    loader = build_detection_train_loader(cfg)
except ValueError as e:
    if "Unknown training sampler" in str(e):
        cfg.DATALOADER.SAMPLER_NAME = "TrainingSampler"
        loader = build_detection_train_loader(cfg)
    else:
        raise

When it happens

Trigger: Setting cfg.DATALOADER.SAMPLER_NAME = 'my_sampler' or a typo like 'training_sampler' (wrong case), then calling build_detection_train_loader(cfg).

Common situations: Typos/case errors in config yaml; version drift where a sampler name was removed/renamed; users expecting custom samplers to be auto-discovered.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• total_batch_size and single_gpu_batch_size are mutually inco
• Class with @configurable must have a 'from_config' classmeth
• {name} must take 'cfg' as the first argument!
• anchor_boundary_thresh is a legacy option not implemented fo
• bias_lr_factor requires base_lr

AI-assisted analysis of facebookresearch/detectron2@a2f4a8771a (2026-08-27). Data as JSON: /api/errors/a73111783ad88f20. Report an issue: GitHub.