{"record":{"id":"527246a20db102df","repo":"matplotlib/matplotlib","slug":"collabels-cannot-be-used-alongside-pandas-datafram","errorCode":null,"errorMessage":"colLabels cannot be used alongside Pandas DataFrame","messagePattern":"colLabels cannot be used alongside Pandas DataFrame","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"lib/matplotlib/table.py","lineNumber":769,"sourceCode":"    # Check we have some cellText\n    if cellText is None:\n        # assume just colours are needed\n        rows = len(cellColours)\n        cols = len(cellColours[0])\n        cellText = [[''] * cols] * rows\n\n    # Check if we have a Pandas DataFrame\n    if _is_pandas_dataframe(cellText):\n        # if rowLabels/colLabels are empty, use DataFrame entries.\n        # Otherwise, throw an error.\n        if rowLabels is None:\n            rowLabels = cellText.index\n        else:\n            raise ValueError(\"rowLabels cannot be used alongside Pandas DataFrame\")\n        if colLabels is None:\n            colLabels = cellText.columns\n        else:\n            raise ValueError(\"colLabels cannot be used alongside Pandas DataFrame\")\n        # Update cellText with only values\n        cellText = cellText.values\n\n    rows = len(cellText)\n    cols = len(cellText[0])\n    for row in cellText:\n        if len(row) != cols:\n            raise ValueError(f\"Each row in 'cellText' must have {cols} \"\n                             \"columns\")\n\n    if cellColours is not None:\n        if len(cellColours) != rows:\n            raise ValueError(f\"'cellColours' must have {rows} rows\")\n        for row in cellColours:\n            if len(row) != cols:\n                raise ValueError(\"Each row in 'cellColours' must have \"\n                                 f\"{cols} columns\")\n    else:","sourceCodeStart":751,"sourceCodeEnd":787,"githubUrl":"https://github.com/matplotlib/matplotlib/blob/b379c1b69e012b142c0f496a52bcb30513802d72/lib/matplotlib/table.py#L751-L787","documentation":"The DataFrame branch of table() also adopts df.columns as colLabels; passing colLabels together with a pandas DataFrame raises ValueError (table.py:769). Same contract as rowLabels: a DataFrame must own its labels, an array must be given them explicitly.","triggerScenarios":"ax.table(cellText=df, colLabels=['a', 'b', 'c']); helpers that always set colLabels from an external schema, then receive DataFrames that already carry column names.","commonSituations":"Schema-driven report generators passing column names that duplicate df.columns; refactoring list input to DataFrames without removing the label arguments.","solutions":["Drop colLabels — df.columns is used automatically","Or pass plain values: ax.table(cellText=df.values, colLabels=list(df.columns))","When renaming is the goal, rename on the DataFrame first: df.rename(columns=...) then ax.table(cellText=df)"],"exampleFix":"# before\nax.table(cellText=df, colLabels=list(df.columns))  # ValueError: colLabels cannot ...\n\n# after: the DataFrame's own columns are used\nax.table(cellText=df)","handlingStrategy":"validation","validationCode":"def safe_table(ax, cellText=None, colLabels=None, **kw):\n    if _is_pandas_dataframe(cellText) and colLabels is not None:\n        raise ValueError(\n            'colLabels conflicts with a DataFrame; its columns are used automatically — '\n            'pass cellText=df.values to keep custom labels')\n    return ax.table(cellText=cellText, colLabels=colLabels, **kw)","typeGuard":"def is_dataframe(v) -> bool:\n    return hasattr(v, 'iloc') and hasattr(v, 'columns')","tryCatchPattern":"try:\n    ax.table(cellText=data, colLabels=col_labels)\nexcept ValueError as e:\n    if 'colLabels' in str(e) and is_dataframe(data):\n        col_labels = None                      # DataFrame owns the labels\n        ax.table(cellText=data, colLabels=col_labels)\n    else:\n        raise","preventionTips":["Rename columns on the DataFrame (df.rename) instead of overriding via colLabels","Validate label kwargs against input type in one wrapper used by all report code","Keep DataFrame/Array table paths in separate, explicitly typed functions"],"tags":["matplotlib","table","pandas","valueerror","dataframe"],"backgroundTag":"conflicting-arguments","analyzedSha":"b379c1b69e012b142c0f496a52bcb30513802d72","analyzedAt":"2026-08-21T23:31:55.468Z","schemaVersion":2},"datasetVersion":"2026-08-22T04:17:13.399Z"}