6. Warning: Possible column misalignment

When scrolling is enabled in DataTables through the use of the scrollX or scrollY parameters, it will split the table into two or three individual HTML table elements; the header, the body and, optionally, the footer. This is done in order to provide the ability to scroll the different sections of the DataTable in a cross browser manner.

The warning:

Warning: Possible column misalignment

will occur when DataTables is unable to align the columns correctly between the different tables. The effect can be a little disconcerting for end-users since header, body and footer columns might not align properly, so it is important to address this error if it occurs on your site.

Meaning

When DataTables performs a draw with scrolling enabled, it will apply a consistent width to the columns in the table in order to have the columns align across the two or three scrolling components of the table. When this is done, DataTables will perform a sanity check to see if the columns have aligned (note that this sanity check is not full-proof! Column misalignment can occur without this error being shown - a complete check would hamper performance of the table). If the sanity check fails, the warning will be shown.

Basically it means that there is a high likelihood of the columns being visually misaligned.

Diagnosis

Fundamentally this is likely to be caused by the table being drawn in a space which is too small for the content in the table. For example, a table with content totalling 500px width, cannot be drawn in a space smaller than that. The header might be able to, but the body content cannot be, hence the misalignment.

Using your browser's developer tools, specifically the Inspect element option to view the live DOM, it is possible to inspect the HTML elements of your page and find which is restricting the table's width.

Resolution

This warning can by triggered due to a number of different configurations in your HTML page, and from your DataTables initialisation. These are:

  • If you are using vertical scrolling (scrollY) and not horizontal scrolling (scrollX), enable the horizontal scrolling option so the table has space to scroll into.
  • If you are using the scrollXInner or sScrollXInner options - remove them. These options force the inner table to a particular width, which might not be appropriate for the content of the table. As of DataTables 1.10 these options are undocumented, as they cause more harm than help, but are retained for backwards compatibility. If you wish to have the content of each row in your table on one line, the typical use of these parameters, use the following CSS:
table.dataTable tbody th,
table.dataTable tbody td {
    white-space: nowrap;
}