4. Warning: Requested unknown parameter

This is possibly the most cryptic warning message that DataTables will show. It is a short error message as it needs to cope with all of the data source options that DataTables has, but flexible enough to convey information for each of these cases, hence why it can appear a little cryptic on first inspection. However, when we break it down into its component parts, it is actually relatively straight forward, as described below.

Meaning

Each cell in DataTables requests data, and when DataTables tries to obtain data for a cell and is unable to do so, it will trigger a warning, telling you that data is not available where it was expected to be. The warning message is:

DataTables warning: table id={id} - Requested unknown parameter '{parameter}' for row {row-index}, column{column-index}`

where:

  • {id} is replaced with the DOM id of the table that has triggered the error
  • {parameter} is the name of the data parameter DataTables is requesting
  • {row-index} is the DataTables internal row index (row().index()) for the row that has triggered the error.
  • {column-index} is the column data index (column().index()) for the column that has triggered the error. The column index information was added in DataTables 1.10.10.

So to break it down, DataTables has requested data for a given row, of the {parameter} provided and there is no data there, or it is null or undefined (DataTables doesn't know, by default how to display these parameters - see below if your data does contain these values).

Diagnosis

The key part to understanding this error message is the {parameter} aspect of it. It will be in one of three forms:

  • Integer
  • String
  • Function

Parameter is an integer

When {parameter} is an integer, DataTables is looking for data from an array. This is usually the case when using DOM sourced data (i.e. the data for the table is read automatically from the document). In this circumstance the requested data doesn't exist in source array - likely because the array isn't long enough. This can occur if:

  • There is a colspan or rowspan in the tbody of the table, which is not supported by DataTables.
  • Using columns or columnDefs you have specified more columns than there are in the HTML
  • The number of cells in the table does not satisfy the equation #cells = #columns * #rows (i.e. there are more columns defined in the header than in the table body, or vice-versa).

Parameter is a string

If {parameter} is shown as a string, this will typically indicate that you have used columns.data or columns.render to pull data out of an object, be it Ajax loaded or from the client-side. For example the error message in read: Requested unknown parameter 'Name' for row 0. This will indicate that a column which uses columns.data has been unable to obtain valid data to display - for example:

{ data: 'Name' }

would produce this error if the data source object for the row had no Name parameter or the data was null or undefined.

As a result, this error usually occurs if:

  • The data property specified doesn't exist (a typo or a gap in data)
  • The value of the property specified is null

Parameter is a function

If {parameter} simply says {function} it means that columns.data or columns.render have been given as a function, but the function has returned null or undefined. For example, the following would trigger such an error:

{ data: function ( row, type, set ) {
    if ( type === 'display' ) {
        return row.Name;
    }
} );

Note how the return statement is only used when type === 'display'. As a result, if type is not display then undefined is the return value from the function and DataTables will throw a warning.

Resolution

The key to resolving this error, is to ensure that DataTables has all of the data that is required. Specifically, check the following:

  • colspan and rowspan have not been used in the tbody of the table.
  • The equation #cells = #columns * #rows is satisfied.
  • If using columns ensure that you have specified exactly the number of columns that are present in the HTML for the table.
  • Also if using `dt-init columns, remove any trailing commas you might have at the end of the array. The additional comma can cause issues for older browsers.
  • If using dt-init columnDefs` ensure that you have not specified more columns than there are in the HTML
  • If using columns.render or columns.data ensure that they are returning a value (no return in Javascript is the same as returning undefined which will result in this error).
  • Ensure that the server-side script is completing its execution successfully. Long running scripts can time out for example. The server error logs will give an indication if this is the case.

null or undefined data

null and undefined values in a data source absolutely are valid and very often useful. DataTables warns about the use of them by default, as the majority of the time they are not intended for display - for example, rather than showing null in the table, you might want to show Not yet set, or simply an empty string (empty cell). For this, DataTables has a columns.defaultContent option.

With columns.defaultContent set, any null or undefined value will be replaced with the value specified. No warning will be shown in this circumstances.