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

CocoPanopticMetric.__init__ rejects the deprecated `file_client_args` argument; like CocoMetric, file access must be configured through `backend_args` (mmengine fileio backends) in mmdetection 3.x. Passing the old parameter raises RuntimeError immediately with a pointer to the reference config. This is a deliberate hard break of the legacy file-client API.

Source

Thrown at mmdet/evaluation/metrics/coco_panoptic_metric.py:115

        self.tmp_dir = None
        # outfile_prefix should be a prefix of a path which points to a shared
        # storage when train or test with multi nodes.
        self.outfile_prefix = outfile_prefix
        if outfile_prefix is None:
            self.tmp_dir = tempfile.TemporaryDirectory()
            self.outfile_prefix = osp.join(self.tmp_dir.name, 'results')
        # the directory to save predicted panoptic segmentation mask
        self.seg_out_dir = f'{self.outfile_prefix}.panoptic'
        self.nproc = nproc
        self.seg_prefix = seg_prefix

        self.cat_ids = None
        self.cat2label = None

        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:
            with get_local_path(
                    ann_file, backend_args=self.backend_args) as local_path:
                self._coco_api = COCOPanoptic(local_path)
            self.categories = self._coco_api.cats
        else:
            self._coco_api = None
            self.categories = None

    def __del__(self) -> None:
        """Clean up."""
        if self.tmp_dir is not None:
            self.tmp_dir.cleanup()

View on GitHub (pinned to cfd5d3a985)

Solutions

Delete file_client_args and set backend_args (e.g. dict(backend='local') or dict(backend='petrel', path_mapping={...}))
Update subclass __init__ signatures to accept backend_args only
Compare against configs/_base_/datasets/coco_detection.py for the new style

Example fix

# before
test_evaluator = dict(type='CocoPanopticMetric', file_client_args=dict(backend='disk'))
# after
test_evaluator = dict(type='CocoPanopticMetric', backend_args=dict(backend='local'))

Defensive patterns

Strategy: validation

Validate before calling

for key in ('val_evaluator','test_evaluator'):
    if key in cfg and 'file_client_args' in cfg[key]:
        raise ValueError(f'{key}: file_client_args deprecated; use backend_args')

Type guard

def evaluator_cfg_is_v3(eval_cfg: dict) -> bool:
    return isinstance(eval_cfg, dict) and 'file_client_args' not in eval_cfg

Prevention

Automated config checks rejecting file_client_args in CI
Keep one canonical backend_args snippet and reuse it
For petrel/s3 backends, also migrate path_mapping into backend_args

When it happens

Trigger: Calling CocoPanopticMetric(..., file_client_args={...}) or a panoptic test config that still has file_client_args in its evaluator dict after upgrading mmdet.

Common situations: Migrating 2.x-era panoptic configs; custom evaluators subclassing CocoPanopticMetric that forward old kwargs; configs copied from projects using ceph/petl via file_client_args.

Related errors

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