{"record":{"id":"130ba817e929daa5","repo":"pola-rs/polars","slug":"infer-schema-length-should-be-positive","errorCode":null,"errorMessage":"'infer_schema_length' should be positive","messagePattern":"'infer_schema_length' should be positive","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/io/ndjson.py","lineNumber":319,"sourceCode":"        Include the path of the source file(s) as a column with this name.\n    \"\"\"\n    sources: list[str] | list[Path] | list[IO[str]] | list[IO[bytes]] = []\n    if isinstance(source, (str, Path)):\n        source = normalize_filepath(source, check_not_directory=False)\n    elif isinstance(source, list):\n        if is_path_or_str_sequence(source):\n            sources = [\n                normalize_filepath(source, check_not_directory=False)\n                for source in source\n            ]\n        else:\n            sources = source\n\n        source = None  # type: ignore[assignment]\n\n    if infer_schema_length == 0:\n        msg = \"'infer_schema_length' should be positive\"\n        raise ValueError(msg)\n\n    if retries is not None:\n        msg = \"the `retries` parameter was deprecated in 1.37.1; specify 'max_retries' in `storage_options` instead.\"\n        issue_deprecation_warning(msg)\n        storage_options = storage_options or {}\n        storage_options[\"max_retries\"] = retries\n\n    if file_cache_ttl is not None:\n        msg = \"file cache is no longer supported as of 1.39.0.\"\n        issue_deprecation_warning(msg)\n\n    credential_provider_builder = _init_credential_provider_builder(\n        credential_provider, source, storage_options, \"scan_ndjson\"\n    )\n\n    del credential_provider\n\n    pylf = PyLazyFrame.new_from_ndjson(","sourceCodeStart":301,"sourceCodeEnd":337,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/io/ndjson.py#L301-L337","documentation":"Raised by pl.scan_ndjson (and pl.read_ndjson, which wraps it) when infer_schema_length is exactly 0. NDJSON schema inference uses sampled records to build the schema, so a zero-length sample is meaningless; unlike some CSV paths where 0 disables inference, polars requires this value to be positive (or None). The check runs after source normalization and before any scan work starts.","triggerScenarios":"Calling pl.read_ndjson('data.ndjson', infer_schema_length=0) or pl.scan_ndjson(..., infer_schema_length=0). Also happens when infer_schema_length is computed (e.g. min(len(preview), 0) or a config value that resolves to 0) and passed through unchanged.","commonSituations":"Copy-pasting CSV-reading code where infer_schema_length=0 was used to mean 'take all rows' or 'no inference'; downstream code that derives the value from an empty sample or a CLI flag defaulting to 0; refactors that changed None to 0 assuming they are equivalent.","solutions":["Pass a positive integer such as infer_schema_length=100 (the default) to sample that many rows.","Pass infer_schema_length=None to scan every record for schema inference when you need the full-file schema.","If you intended 'do not infer', instead pass an explicit schema via schema_overrides/schema so inference is not needed.","Trace where the 0 comes from (CLI arg, config, computed value) and clamp it to a positive default before calling polars."],"exampleFix":"// before\npl.read_ndjson('events.ndjson', infer_schema_length=0)  # ValueError\n\n// after\npl.read_ndjson('events.ndjson', infer_schema_length=100)  # or None to infer from all rows","handlingStrategy":"validation","validationCode":"def safe_infer_schema_length(n):\n    if n == 0:\n        return None  # infer from all rows, or a positive default like 100\n    return n\n\npl.read_ndjson(path, infer_schema_length=safe_infer_schema_length(n))","typeGuard":"def is_valid_infer_schema_length(n: object) -> bool:\n    return n is None or (isinstance(n, int) and not isinstance(n, bool) and n > 0)","tryCatchPattern":"try:\n    df = pl.read_ndjson(path, infer_schema_length=n)\nexcept ValueError as e:\n    if 'infer_schema_length' in str(e):\n        n = None\n        df = pl.read_ndjson(path, infer_schema_length=n)\n    else:\n        raise","preventionTips":["Never use 0 to mean 'no inference' with NDJSON — use None or a positive sample size.","Centralize infer_schema_length in one config helper that clamps to a positive int or None.","Add a unit test asserting your config never resolves infer_schema_length to 0."],"tags":["ndjson","json","schema-inference","parameter-validation","io"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}