What causes "Unknown training sampler: {}" in facebookresearch/detectron2?

Fix the name to one of the supported values (check the elif chain in detectron2/data/build.py)

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.

Solutions

Fix the name to one of the supported values (check the elif chain in detectron2/data/build.py)
For custom sampling, implement a custom build_detection_train_loader that constructs your sampler directly
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"

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

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

Prevention

Copy sampler names verbatim from defaults.py
Add config validation at startup
Write a custom loader builder for custom samplers instead of the name registry

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

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

Appendix: 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)