open-mmlab/mmdetection · error · RuntimeError

The `file_client_args` is deprecated, please use `backend_ar

Error message

The `file_client_args` is deprecated, please use `backend_args` instead, please refer tohttps://github.com/open-mmlab/mmdetection/blob/main/configs/_base_/datasets/coco_detection.py

What it means

BaseDetDataset (all mmdet detection datasets) removed support for file_client_args in the MMEngine migration; passing it now raises a RuntimeError pointing at backend_args. File client behavior (disk/ceph/http backends) is configured through backend_args (mmengine.fileio) instead. This is a hard deprecation, not a warning.

Source

Thrown at mmdet/datasets/base_det_dataset.py:46

    def __init__(self,
                 *args,
                 seg_map_suffix: str = '.png',
                 proposal_file: Optional[str] = None,
                 file_client_args: dict = None,
                 backend_args: dict = None,
                 return_classes: bool = False,
                 caption_prompt: Optional[dict] = None,
                 **kwargs) -> None:
        self.seg_map_suffix = seg_map_suffix
        self.proposal_file = proposal_file
        self.backend_args = backend_args
        self.return_classes = return_classes
        self.caption_prompt = caption_prompt
        if self.caption_prompt is not None:
            assert self.return_classes, \
                'return_classes must be True when using caption_prompt'
        if file_client_args is not None:
            raise RuntimeError(
                'The `file_client_args` is deprecated, '
                'please use `backend_args` instead, please refer to'
                'https://github.com/open-mmlab/mmdetection/blob/main/configs/_base_/datasets/coco_detection.py'  # noqa: E501
            )
        super().__init__(*args, **kwargs)

    def full_init(self) -> None:
        """Load annotation file and set ``BaseDataset._fully_initialized`` to
        True.

        If ``lazy_init=False``, ``full_init`` will be called during the
        instantiation and ``self._fully_initialized`` will be set to True. If
        ``obj._fully_initialized=False``, the class method decorated by
        ``force_full_init`` will call ``full_init`` automatically.

        Several steps to initialize annotation:

            - load_data_list: Load annotations from annotation file.

View on GitHub (pinned to cfd5d3a985)

Solutions

  1. Delete the file_client_args entry from the dataset config (plain disk access needs no backend_args)
  2. For non-local storage, set backend_args instead, e.g. backend_args=dict(backend='petrel', path_mapping=dict({'./data/': 's3://data/'}))
  3. Use mmdet's config migration tool / follow configs/_base_/datasets/coco_detection.py in the current repo as the reference
  4. After editing, re-parse the config with Config.fromfile to confirm no stale keys remain

Example fix

# before
train_dataloader=dict(
  dataset=dict(type='CocoDataset', data_root='data/', ann_file='train.json',
               data_prefix=dict(img='train/'),
               file_client_args=dict(backend='disk')))
# after
train_dataloader=dict(
  dataset=dict(type='CocoDataset', data_root='data/', ann_file='train.json',
               data_prefix=dict(img='train/')))
# or for ceph:
  # backend_args=dict(backend='petrel', path_mapping=dict({'./data/': 's3://bucket/data/'}))
Defensive patterns

Strategy: validation

Validate before calling

cfg = Config.fromfile(config_path)
for name in ('train_dataloader', 'val_dataloader', 'test_dataloader'):
    ds = cfg.get(name, {}).get('dataset', {})
    if isinstance(ds, dict) and 'file_client_args' in ds:
        ds.pop('file_client_args')  # or move to backend_args
cfg.dump(config_path)

Type guard

def uses_deprecated_file_client(cfg) -> bool:
    return any('file_client_args' in (cfg.get(n, {}).get('dataset') or {})
               for n in ('train_dataloader', 'val_dataloader', 'test_dataloader'))

Try / catch

try:
    runner = Runner.from_cfg(cfg)
except RuntimeError as e:
    if 'file_client_args' in str(e):
        raise SystemExit('Remove file_client_args from dataset configs; use backend_args (see configs/_base_/datasets/coco_detection.py)')
    raise

Prevention

When it happens

Trigger: Instantiating any mmdet dataset class (or building a dataloader from a config) whose init kwargs include file_client_args — typically configs carried over from mmdet 2.x or from older projects.

Common situations: Upgrading mmdet 2.x configs to 3.x; copying dataset config blocks from old repos/tutorials that set file_client_args=dict(backend='disk'); internal clusters that used ceph via file_client_args.

Related errors

AI-assisted analysis of open-mmlab/mmdetection@cfd5d3a985 (2026-08-27). Data as JSON: /api/errors/f3b7d660055273ac. Report an issue: GitHub.