{"record":{"id":"c7f260880ddd183a","repo":"pola-rs/polars","slug":"writing-df-height-x-df-width-frame-at-position","errorCode":null,"errorMessage":"writing {df.height}x{df.width} frame at {position!r} does not fit worksheet dimensions of {excel_max_valid_rows} rows and {excel_max_valid_cols} columns","messagePattern":"writing (.+?)x(.+?) frame at (.+?) does not fit worksheet dimensions of (.+?) rows and (.+?) columns","errorType":"exception","errorClass":"InvalidOperationError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/dataframe/frame.py","lineNumber":3810,"sourceCode":"        )\n        table_finish = (\n            table_start[0]\n            + df.height\n            + int(is_empty)\n            - int(not include_header)\n            + int(bool(column_totals)),\n            table_start[1] + df.width - 1,\n        )\n\n        excel_max_valid_rows = 1048575\n        excel_max_valid_cols = 16384\n\n        if (\n            table_finish[0] > excel_max_valid_rows\n            or table_finish[1] > excel_max_valid_cols\n        ):\n            msg = f\"writing {df.height}x{df.width} frame at {position!r} does not fit worksheet dimensions of {excel_max_valid_rows} rows and {excel_max_valid_cols} columns\"\n            raise InvalidOperationError(msg)\n\n        # write table structure and formats into the target sheet\n        if not is_empty or include_header:\n            ws.add_table(\n                *table_start,\n                *table_finish,\n                {\n                    \"data\": df.rows(),\n                    \"style\": table_style,\n                    \"columns\": table_columns,\n                    \"header_row\": include_header,\n                    \"autofilter\": autofilter,\n                    \"total_row\": bool(column_totals) and not is_empty,\n                    \"name\": table_name,\n                    **table_options,\n                },\n            )\n","sourceCodeStart":3792,"sourceCodeEnd":3828,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/dataframe/frame.py#L3792-L3828","documentation":"Raised as InvalidOperationError by DataFrame.write_excel when the table (frame dimensions plus its start position and any header/totals rows/columns) extends beyond a worksheet's hard limits: 1,048,575 rows and 16,384 columns (xlsx caps). Polars computes the finish cell from `position`, df.height/width, include_header and column_totals, then rejects the write up front rather than emitting a corrupt file that Excel refuses to open.","triggerScenarios":"Writing a frame with more than ~1,048,575 rows; or a wide frame over 16,384 columns; or a smaller frame placed at a large position like 'XFD1048576' (or a (row, col) tuple near the limits) such that table_finish exceeds the bounds — e.g. a 100k-row frame started at row 1,000,000.","commonSituations":"Exporting large query results straight to xlsx for analysts; writing multiple frames stacked into one sheet via `position` offsets where an early frame pushes a later one past the boundary; timestamps/IDs pivoted into very wide frames; automated report generation that assumes arbitrary output size.","solutions":["Split the frame across sheets or files: write in chunks of <= ~1M rows with `xlsx.write_frame` on separate worksheets","Start tables at 'A1' / small positions so the position offset doesn't consume the budget","Drop columns or write wide frames transposed; or export to CSV/Parquet when data exceeds Excel's model","Guard before writing: `if df.height > 1_048_575 or df.width > 16_384: ...` route to a different format"],"exampleFix":"# before\ndf.write_excel(workbook='out.xlsx', position='A1040000')\n\n# after\nwith pl.ExcelWriter('out.xlsx') as xlsx:\n    df.write_excel(workbook=xlsx, worksheet='data')\n    # large frames: chunk across sheets/rows starting near A1","handlingStrategy":"validation","validationCode":"EXCEL_MAX_ROWS, EXCEL_MAX_COLS = 1048575, 16384\nstart_row, start_col = 1, 1  # from your position; 'A1' == (1, 1)\nextra_rows = int(include_header) + int(bool(column_totals))\nif start_row + df.height - 1 + extra_rows > EXCEL_MAX_ROWS or start_col + df.width - 1 > EXCEL_MAX_COLS:\n    raise ValueError('frame does not fit the target worksheet; chunk or change format')\ndf.write_excel('out.xlsx', position=position)","typeGuard":null,"tryCatchPattern":"try:\n    df.write_excel('out.xlsx', position=position)\nexcept pl.exceptions.InvalidOperationError as e:\n    if 'does not fit worksheet dimensions' in str(e):\n        df.write_csv('out.csv.gz')  # or chunk across sheets\n    else:\n        raise","preventionTips":["Route frames larger than ~1M rows or 16k columns to CSV/Parquet instead of xlsx","Track the next free row yourself when stacking frames so positions never near 1,048,575","Assert output size limits in automated report pipelines before the Excel write"],"tags":["excel","limits-exceeded","export","xlsxwriter"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}