{"record":{"id":"d69e1d3c4d82d634","repo":"pola-rs/polars","slug":"name-is-not-supported-by-the-remote-engine","errorCode":null,"errorMessage":"`{name}` is not supported by the remote engine","messagePattern":"`(.+?)` is not supported by the remote engine","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/lazyframe/engine_remote.py","lineNumber":230,"sourceCode":"    def _sink_uri(path: Any) -> str | PartitionBy:\n        \"\"\"Validate a Polars Cloud sink target.\"\"\"\n        from polars.io.partition import PartitionBy\n\n        if not isinstance(path, (str, PartitionBy)):\n            msg = (\n                \"the remote engine can only sink to a URI or a `PartitionBy`, got \"\n                f\"{qualified_type_name(path)!r}\"\n            )\n            raise TypeError(msg)\n        return path\n\n    @staticmethod\n    def _reject_if_set(**kwargs: Any) -> None:\n        \"\"\"Reject options unsupported by Polars Cloud.\"\"\"\n        for name, value in kwargs.items():\n            if value:\n                msg = f\"`{name}` is not supported by the remote engine\"\n                raise ValueError(msg)\n\n    def sink_parquet(\n        self,\n        lf: LazyFrame,\n        path: str | Path | IO[bytes] | PartitionBy,\n        *,\n        compression: ParquetCompression,\n        compression_level: int | None,\n        statistics: bool | str | dict[str, bool],\n        row_group_size: int | None,\n        data_page_size: int | None,\n        maintain_order: bool,\n        storage_options: StorageOptionsDict | None,\n        credential_provider: CredentialProviderFunction | Literal[\"auto\"] | None,\n        retries: int | None,\n        sync_on_close: SyncOnCloseMethod | None,\n        metadata: ParquetMetadata | None,\n        arrow_schema: ArrowSchemaExportable | None,","sourceCodeStart":212,"sourceCodeEnd":248,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/lazyframe/engine_remote.py#L212-L248","documentation":"`RemoteEngine._reject_if_set` (engine_remote.py:225) enforces the option subset Polars Cloud actually supports: any sink option that is set to a truthy value gets `ValueError: '`name` is not supported by the remote engine'`. Per sink: parquet rejects `lazy`, `mkdir`, `sync_on_close`, `retries`, `sinked_paths_callback`; ipc additionally rejects `record_batch_size`, `_record_batch_statistics`, and `maintain_order=False` (passed as `not maintain_order`); csv additionally rejects any `compression` other than `'uncompressed'`, `compression_level`, `check_extension=False`, and `maintain_order=False`.","triggerScenarios":"`lf.sink_csv('s3://b/out.csv', engine=remote, compression='gzip')`; `lf.sink_parquet(uri, engine=remote, mkdir=True)`; `lf.sink_ipc(uri, engine=remote, record_batch_size=1000)`; any remote sink with `lazy=True` or `sync_on_close='data'` or `maintain_order=False` (ipc/csv).","commonSituations":"A sink helper with many keyword options reused for both local and remote engines; compressed CSV output required by a consumer while data must land in cloud storage; replicating local sink flags verbatim when moving to Polars Cloud.","solutions":["Drop the unsupported option for remote sinks (defaults are the supported behavior)","For compressed CSV output, write uncompressed remotely then compress in a downstream step, or run locally: `lf.sink_csv(path, compression='gzip', engine='streaming')`","If you need `lazy=True`, `mkdir`, or `sync_on_close`, use a local engine for that sink","If `maintain_order` matters for ipc/csv remotely, note Polars Cloud only supports `maintain_order=True`"],"exampleFix":"# before\nlf.sink_csv('s3://bucket/out.csv', engine=remote, compression='gzip')  # ValueError\n\n# after\nlf.sink_csv('s3://bucket/out.csv', engine=remote)  # uncompressed\n# or compress locally:\nlf.sink_csv('out.csv.gz', compression='gzip', engine='streaming')","handlingStrategy":"validation","validationCode":"REMOTE_FORBIDDEN = {\n    'parquet': {'lazy', 'mkdir', 'sync_on_close', 'retries', 'sinked_paths_callback'},\n    'ipc': {'lazy', 'mkdir', 'sync_on_close', 'retries', 'sinked_paths_callback',\n            'record_batch_size', '_record_batch_statistics'},\n    'csv': {'lazy', 'mkdir', 'sync_on_close', 'retries', 'compression_level',\n            'check_extension'},\n}\n\ndef check_remote_sink_kwargs(fmt: str, kwargs: dict) -> None:\n    bad = [k for k in REMOTE_FORBIDDEN[fmt] if kwargs.get(k)]\n    if fmt == 'csv' and kwargs.get('compression') not in (None, 'uncompressed'):\n        bad.append('compression')\n    if fmt in ('ipc', 'csv') and kwargs.get('maintain_order') is False:\n        bad.append('maintain_order')\n    if bad:\n        raise ValueError(f'options not supported by the remote engine: {sorted(bad)}')","typeGuard":null,"tryCatchPattern":"try:\n    lf.sink_csv(uri, engine=remote, **sink_opts)\nexcept ValueError as e:\n    if 'not supported by the remote engine' in str(e):\n        lf.sink_csv(uri, engine=remote)  # retry with defaults\n    else:\n        raise","preventionTips":["Keep a dedicated minimal kwargs dict for remote sinks; do not share the local one","Remote CSV is uncompressed only; compress downstream or sink locally","Remote ipc/csv always maintain order; do not pass maintain_order=False","Construct RemoteEngine and run one tiny sink at startup to surface option conflicts early"],"tags":["polars","remote","cloud","sink","options","valueerror"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}