pola-rs/polars · error

table width argument does not fit in u16

Error message

table width argument does not fit in u16

What it means

When rendering a table, Polars reads the POLARS_FMT_TBL_WIDTH environment variable and parses it as i64, then converts it to u16 for internal width handling. The panic fires when the parsed value does not fit in a u16 (i.e. it is greater than 65535; negative values are mapped to u16::MAX and never reach this check). This means the configured display width exceeds the maximum the formatter supports.

Solutions

1. Set POLARS_FMT_TBL_WIDTH to a value between 0 and 65535.
2. Unset POLARS_FMT_TBL_WIDTH to fall back to the default width behavior.
3. If unlimited width is intended, remove negative/huge sentinels and rely on the default or u16::MAX-equivalent values the formatter already treats as very wide.

Example fix

// before
export POLARS_FMT_TBL_WIDTH=999999

// after
export POLARS_FMT_TBL_WIDTH=200

let v: i64 = std::env::var("POLARS_FMT_TBL_WIDTH")?.parse()?;
assert!((0..=u16::MAX as i64).contains(&v), "POLARS_FMT_TBL_WIDTH must be 0..=65535");

When it happens

Trigger: Setting POLARS_FMT_TBL_WIDTH to a value > 65535 (e.g. 1000000) before running a program or test that prints a DataFrame with `fmt`/`Display`.

Common situations: Users exporting a shell config with a huge table-width value assuming it means 'unlimited'; CI scripts that set the env var dynamically from a terminal-width calculation that returns a large number; typos like an extra digit in the value.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• activate 'timezones' feature
• could not parse table width argument
• offset exceeds usize limits
• {0}
• activate dtype

AI-assisted analysis of pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/22d365587af0afe3. Report an issue: GitHub.

Appendix: source

Thrown at crates/polars-core/src/fmt.rs:751

                        } else {
                            break;
                        }
                    }
                }
            } else if height > 0 {
                let dots: Vec<String> = vec![ellipsis; self.width()];
                table.add_row(dots);
            }
            let tbl_fallback_width = 100;
            let tbl_width = std::env::var("POLARS_TABLE_WIDTH")
                .map(|s| {
                    let n = s
                        .parse::<i64>()
                        .expect("could not parse table width argument");
                    let w = if n < 0 {
                        u16::MAX
                    } else {
                        u16::try_from(n).expect("table width argument does not fit in u16")
                    };
                    Some(w)
                })
                .unwrap_or(None);

            // column width constraints
            let col_width_exact =
                |w: usize| ColumnConstraint::Absolute(comfy_table::Width::Fixed(w as u16));
            let col_width_bounds = |l: usize, u: usize| ColumnConstraint::Boundaries {
                lower: Width::Fixed(l as u16),
                upper: Width::Fixed(u as u16),
            };
            let min_col_width = std::cmp::max(5, 3 + padding);
            for (idx, elem_len) in max_elem_lengths.iter().enumerate() {
                let mx = std::cmp::min(
                    str_truncate + ellipsis_len + padding,
                    std::cmp::max(name_lengths[idx], *elem_len),
                );

View on GitHub (pinned to fe841f959e)