pola-rs/polars · error · ValueError

the given workbook object {wb.filename!r} is not the parent

Error message

the given workbook object {wb.filename!r} is not the parent of worksheet {ws.name!r}

What it means

ValueError raised by _xl_worksheet_in_workbook during write_excel when the worksheet passed via the worksheet parameter does not belong to the workbook passed via the workbook parameter. The helper walks wb.worksheets() looking for the exact worksheet object; polars only writes into sheets it can verify are owned by the target workbook, to avoid corrupting another open workbook's state.

Source

Thrown at py-polars/src/polars/io/spreadsheet/_write_utils.py:582


@overload
def _xl_worksheet_in_workbook(
    wb: Workbook, ws: Worksheet, *, return_worksheet: Literal[False] = ...
) -> bool: ...
@overload
def _xl_worksheet_in_workbook(
    wb: Workbook, ws: Worksheet, *, return_worksheet: Literal[True]
) -> Worksheet: ...


def _xl_worksheet_in_workbook(
    wb: Workbook, ws: Worksheet, *, return_worksheet: bool = False
) -> bool | Worksheet:
    if any(ws is sheet for sheet in wb.worksheets()):
        return ws if return_worksheet else True
    msg = f"the given workbook object {wb.filename!r} is not the parent of worksheet {ws.name!r}"
    raise ValueError(msg)


def _xl_setup_workbook(
    workbook: Workbook | IO[bytes] | Path | str | None,
    worksheet: str | Worksheet | None = None,
    *,
    use_zip64: bool = False,
) -> tuple[Workbook, Worksheet, bool]:
    """Establish the target Excel workbook and worksheet."""
    from xlsxwriter import Workbook
    from xlsxwriter.worksheet import Worksheet

    if isinstance(workbook, Workbook):
        wb, can_close = workbook, False
        ws = (
            worksheet
            if (
                isinstance(worksheet, Worksheet)

View on GitHub (pinned to df599052da)

Solutions

Pass the worksheet's actual parent: pl.write_excel(df, workbook=wb2, worksheet=ws_from_wb2).
Or reference the sheet by name within the correct workbook: worksheet='Sheet1' together with workbook=wb.
When iterating sheets across workbooks, keep (workbook, worksheet) pairs together instead of separate lookups.

Example fix

# before
ws = wb_b.add_worksheet('data')
pl.write_excel(df, workbook=wb_a, worksheet=ws)  # ws belongs to wb_b

# after
pl.write_excel(df, workbook=wb_b, worksheet=ws)

Defensive patterns

Strategy: validation

Validate before calling

if worksheet is not None and workbook is not None:
    import xlsxwriter
    assert isinstance(workbook, xlsxwriter.Workbook)
    assert any(worksheet is ws for ws in workbook.worksheets()), 'worksheet does not belong to workbook'
pl.write_excel(df, workbook=workbook, worksheet=worksheet)

Try / catch

try:
    pl.write_excel(df, workbook=wb, worksheet=ws)
except ValueError as e:
    if 'is not the parent of worksheet' in str(e):
        raise ValueError(f'wrong workbook for {ws.name!r}; pass its actual parent Workbook') from e
    raise

Prevention

Always pair a worksheet object with the workbook that produced it.
Reference sheets by name (worksheet='Sheet1') when the pairing could get mixed up.
In loops over multiple workbooks, carry (workbook, worksheet) tuples, never bare handles.

When it happens

Trigger: Creating wb1 = Workbook('a.xlsx') and wb2 = Workbook('b.xlsx'), then pl.write_excel(df, workbook=wb1, worksheet=wb2.get_worksheet_by_name('Sheet1')).

Common situations: Multi-workbook report generation where worksheet handles are stored in a dict and paired with the wrong workbook; refactoring code that creates one workbook per sheet and mixing up variables; appending polars output to a template workbook while passing a worksheet handle from a different template instance.

Related errors

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/5cb91ea5e618a242. Report an issue: GitHub.