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

CocoMetric.__init__ rejects the legacy `file_client_args` parameter that mmengine file clients used before the 'backend_args' migration. Since mmdetection 3.x, file I/O goes through mmcv/filelock-style backends configured via `backend_args`, so passing file_client_args is a hard RuntimeError pointing at the migration doc. It exists to break silently-wrong old configs early.

Source

Thrown at mmdet/evaluation/metrics/coco_metric.py:119

        self.proposal_nums = list(proposal_nums)

        # iou_thrs used to compute recall or precision.
        if iou_thrs is None:
            iou_thrs = np.linspace(
                .5, 0.95, int(np.round((0.95 - .5) / .05)) + 1, endpoint=True)
        self.iou_thrs = iou_thrs
        self.metric_items = metric_items
        self.format_only = format_only
        if self.format_only:
            assert outfile_prefix is not None, 'outfile_prefix must be not'
            'None when format_only is True, otherwise the result files will'
            'be saved to a temp directory which will be cleaned up at the end.'

        self.outfile_prefix = outfile_prefix

        self.backend_args = backend_args
        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
            )

        # if ann_file is not specified,
        # initialize coco api with the converted dataset
        if ann_file is not None:
            with get_local_path(
                    ann_file, backend_args=self.backend_args) as local_path:
                self._coco_api = COCO(local_path)
                if sort_categories:
                    # 'categories' list in objects365_train.json and
                    # objects365_val.json is inconsistent, need sort
                    # list(or dict) before get cat_ids.
                    cats = self._coco_api.cats
                    sorted_cats = {i: cats[i] for i in sorted(cats)}
                    self._coco_api.cats = sorted_cats

View on GitHub (pinned to cfd5d3a985)

Solutions

Remove file_client_args and pass backend_args instead, e.g. backend_args=dict(backend='local') for local files
For remote storage use backend_args=dict(backend='petrel', path_mapping=...)
Diff your config against configs/_base_/datasets/coco_detection.py referenced in the message

Example fix

# before
val_evaluator = dict(type='CocoMetric', ann_file=..., metric='bbox', file_client_args=dict(backend='disk'))
# after
val_evaluator = dict(type='CocoMetric', ann_file=..., metric='bbox', backend_args=dict(backend='local'))

Defensive patterns

Strategy: validation

Validate before calling

def sanitize_evaluator(cfg):
    ev = cfg.get('val_evaluator', cfg.get('test_evaluator', {}))
    if 'file_client_args' in ev:
        raise ValueError('file_client_args removed; migrate to backend_args')
    return cfg

Type guard

def uses_backend_args(eval_cfg: dict) -> bool:
    return 'file_client_args' not in eval_cfg and (
        'backend_args' not in eval_cfg or isinstance(eval_cfg['backend_args'], dict))

Try / catch

try:
    CocoMetric(..., file_client_args=fca)
except RuntimeError as e:
    if 'file_client_args' in str(e):
        raise ValueError('migrate config: replace file_client_args with backend_args') from e
    raise

Prevention

Grep configs for file_client_args after upgrading mmdetection
Prefer omitting backend_args entirely for local files (it defaults correctly)
Pin mmdetection major version in requirements to avoid surprise API breaks

When it happens

Trigger: Calling CocoMetric(..., file_client_args={'backend':'disk'}) or running a config that still carries a file_client_args key in val_evaluator / test_evaluator after upgrading mmdetection to 3.x.

Common situations: Upgrading from mmdet 2.x / early 3.x configs; copy-pasting an old custom evaluator config that specified a petl/ceph client via file_client_args.

Related errors

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