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

LVISMetric.__init__ rejects the deprecated `file_client_args` parameter with RuntimeError, same as the other mmdet v3 evaluators. The fileio layer moved to mmengine backend_args, and any non-None file_client_args triggers an immediate hard failure to force config migration.

Source

Thrown at mmdet/evaluation/metrics/lvis_metric.py:129

        # proposal_nums used to compute recall or precision.
        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 lvis 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._lvis_api = LVIS(local_path)
        else:
            self._lvis_api = None

        # handle dataset lazy init
        self.cat_ids = None
        self.img_ids = None

View on GitHub (pinned to cfd5d3a985)

Solutions

Delete file_client_args from the config and pass backend_args=dict(backend='disk') if non-default I/O is needed
For simple local-disk setups, omit both — backend_args=None defaults to the disk backend
Run the mmengine config migration utility over legacy configs

Example fix

// before
val_evaluator=dict(type='LVISMetric', file_client_args=dict(backend='disk'))
// after
val_evaluator=dict(type='LVISMetric', backend_args=dict(backend='disk'))

Defensive patterns

Strategy: validation

Validate before calling

if evaluator_cfg.get('file_client_args') is not None:
    evaluator_cfg['backend_args'] = evaluator_cfg.pop('file_client_args')
    # or set backend_args={'backend': 'disk'} explicitly

Type guard

def needs_fileio_migration(cfg: dict) -> bool:
    return 'file_client_args' in cfg and cfg['file_client_args'] is not None

Try / catch

try:
    evaluator = LVISMetric(**evaluator_cfg)
except RuntimeError as e:
    if 'file_client_args' in str(e):
        evaluator_cfg.pop('file_client_args', None)
        evaluator = LVISMetric(**evaluator_cfg)
    else:
        raise

Prevention

Migrate configs with the official tool after major upgrades
Search repos for 'file_client_args' before upgrading mmdet
Default to backend_args or no fileio args at all

When it happens

Trigger: Building LVISMetric with file_client_args=dict(backend='disk') or any non-None value, usually inherited from an old LVIS dataset/evaluator config.

Common situations: Reusing an mmdet 2.x LVIS config with mmdet 3.x; copying `file_client_args` blocks from old tutorials; configs from downstream repos (e.g. old DINO/GLIP-era configs) not yet migrated.

Related errors

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