What causes "The task does not contains a handler part." in microsoft/qlib?

Add a handler config under dataset.kwargs, e.g. "handler": {"class": "Alpha158", "kwargs": {"start_time": ..., "end_time": ..., "instruments": ...}}.

microsoft/qlib · error · ValueError

The task does not contains a handler part.

Error message

The task does not contains a handler part.

What it means

Raised by get_dataset_kwargs / the task-unpacking helper (qlib/data/dataset/utils.py) when a task dict's dataset.kwargs contains no 'handler' entry. Qlib task objects (dataset + handler + model) require an embedded DataHandler config; without it there is nothing to instantiate, so a ValueError is raised with the message 'The task does not contains a handler part.'

Source

Thrown at qlib/data/dataset/utils.py:142

    ----------
    task : dict
        the task to be handled

    Returns
    -------
    Union[DataHandler, None]:
        returns
    """
    # avoid recursive import
    from .handler import DataHandler  # pylint: disable=C0415

    h_conf = task["dataset"]["kwargs"].get("handler")
    if h_conf is not None:
        handler = init_instance_by_config(h_conf, accept_types=DataHandler)
        task["dataset"]["kwargs"]["handler"] = handler
        return handler
    else:
        raise ValueError("The task does not contains a handler part.")

View on GitHub (pinned to 79633dd950)

Solutions

Add a handler config under dataset.kwargs, e.g. "handler": {"class": "Alpha158", "kwargs": {"start_time": ..., "end_time": ..., "instruments": ...}}.
If you already have a DataHandler instance, put it directly: task["dataset"]["kwargs"]["handler"] = my_handler — the helper accepts instances (accept_types=DataHandler).
Check that the handler key is not explicitly set to None; remove the key or give it a real config.

Example fix

# before
task = {
  "dataset": {"class": "DatasetH", "kwargs": {"segments": {"train": (...), "valid": (...)}}},
}

# after
task = {
  "dataset": {"class": "DatasetH", "kwargs": {
      "handler": {"class": "Alpha158", "kwargs": {"instruments": "csi300", "start_time": "2010-01-01", "end_time": "2020-12-31"}},
      "segments": {"train": ("2010-01-01", "2017-12-31"), "valid": ("2018-01-01", "2020-12-31")},
  }},
}

Defensive patterns

Strategy: validation

Validate before calling

handler_conf = task.get("dataset", {}).get("kwargs", {}).get("handler")
if handler_conf is None:
    raise ValueError("task['dataset']['kwargs'] must define 'handler'")

Type guard

def task_has_handler(task: dict) -> bool:
    return task.get("dataset", {}).get("kwargs", {}).get("handler") is not None

Prevention

Build task dicts with a factory function that always injects the handler section.
Validate task structure once before submitting to QlibRecorder/Rolling loops.

When it happens

Trigger: init_instance_by_config / task execution where task = {"dataset": {"class": "DatasetH", "kwargs": {"segments": {...}}}} — kwargs has segments but no "handler" key. Also when the handler key exists but its value is None (h_conf is None takes the else branch).

Common situations: Hand-building task dicts for qlib workflows (e.g. Rolling benchmarks, QlibRecorder experiments) and omitting the handler; splitting a config across files and dropping the handler section; setting "handler": None to 'disable' it, which is not supported.

Related errors

AI-assisted analysis of microsoft/qlib@79633dd950 (2026-08-15). Data as JSON: /api/errors/7f96bb5881dcdac2. Report an issue: GitHub.