{"record":{"id":"8626cd2e0119570d","repo":"hiyouga/LlamaFactory","slug":"max-samples-is-incompatible-with-streaming","errorCode":null,"errorMessage":"`max_samples` is incompatible with `streaming`.","messagePattern":"`max_samples` is incompatible with `streaming`\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/hparams/data_args.py","lineNumber":180,"sourceCode":"        if self.eval_dataset is not None and self.val_size > 1e-6:\n            raise ValueError(\"Cannot specify `val_size` if `eval_dataset` is not None.\")\n\n        if self.interleave_probs is not None:\n            if self.mix_strategy == \"concat\":\n                raise ValueError(\"`interleave_probs` is only valid for interleaved mixing.\")\n\n            self.interleave_probs = list(map(float, split_arg(self.interleave_probs)))\n            if self.dataset is not None and len(self.dataset) != len(self.interleave_probs):\n                raise ValueError(\"The length of dataset and interleave probs should be identical.\")\n\n            if self.eval_dataset is not None and len(self.eval_dataset) != len(self.interleave_probs):\n                raise ValueError(\"The length of eval dataset and interleave probs should be identical.\")\n\n        if self.streaming and self.val_size > 1e-6 and self.val_size < 1:\n            raise ValueError(\"Streaming mode should have an integer val size.\")\n\n        if self.streaming and self.max_samples is not None:\n            raise ValueError(\"`max_samples` is incompatible with `streaming`.\")\n\n        if self.mask_history and self.train_on_prompt:\n            raise ValueError(\"`mask_history` is incompatible with `train_on_prompt`.\")\n\n        if self.neat_packing:\n            self.packing = True\n\n        if self.packing:\n            self.cutoff_len -= 1  # avoid pad_to_multiple_of, needs improve\n\n    def to_dict(self) -> dict[str, Any]:\n        return asdict(self)\n","sourceCodeStart":162,"sourceCodeEnd":193,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/hparams/data_args.py#L162-L193","documentation":"max_samples truncates a dataset by indexing the first N examples, which requires random access. Streaming datasets are IterableDatasets and cannot be indexed, so DataArguments.__post_init__ (src/llamafactory/hparams/data_args.py:180) forbids the combination. To limit a stream, use max_steps in the training arguments instead.","triggerScenarios":"A training config with both streaming: true and max_samples: N (N any integer). Raised at argument-parsing time in DataArguments.__post_init__ before dataset construction.","commonSituations":"Users add max_samples: 1000 for a quick smoke-test run on a huge streamed dataset (common when testing a pipeline before a full run). Also occurs when reusing a debug config that had max_samples set and then enabling streaming for scale.","solutions":["Remove max_samples from the config and limit the run with max_steps (or steps in the trainer) instead.","If you only need a small fixed dataset, disable streaming (streaming: false) and keep max_samples.","For debugging, use a small streamed dataset by name and stop early via max_steps / eval_steps."],"exampleFix":"# before (yaml)\nstreaming: true\nmax_samples: 1000\n\n# after (yaml)\nstreaming: true\n# max_samples removed; limit training length instead\nmax_steps: 500","handlingStrategy":"validation","validationCode":"def check_streaming_max_samples(streaming: bool, max_samples: int | None) -> None:\n    if streaming and max_samples is not None:\n        raise ValueError(\"max_samples cannot be used with streaming=True; use max_steps instead\")","typeGuard":null,"tryCatchPattern":"try:\n    data_args = DataArguments(dataset=..., streaming=True, max_samples=1000)\nexcept ValueError as e:\n    raise SystemExit(f\"Invalid data config: {e}\")","preventionTips":["For smoke tests on streamed datasets, budget the run with max_steps, never max_samples.","CI lint rule: reject configs containing both streaming: true and max_samples."],"tags":["config","streaming","data","sampling"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}