Hmbown/CodeWhale · error

PTY rows and columns must each be between 1 and 1000

Error message

PTY rows and columns must each be between 1 and 1000

What it means

PtyDimensions::validate enforces that both the PTY row and column counts are within the inclusive range 1..=1000 before a pseudo-terminal is created. This guards the TUI shell tool against callers passing nonsensical terminal sizes (zero, negative, or absurdly large) that would break downstream PTY allocation APIs. It is thrown via anyhow::ensure! when either dimension falls outside that range.

Solutions

1. Check the rows/cols values passed into the shell tool call and clamp them to 1..=1000 before invoking.
2. If dimensions are absent, use the default (24x80) rather than 0.
3. Verify any unsigned-to-signed conversion of terminal sizes is not underflowing to 0 or wrapping.

Example fix

// before
let pty = PtyDimensions { rows: 0, cols: 0 }.validate()?;

// after
let pty = PtyDimensions {
    rows: rows.clamp(1, 1000),
    cols: cols.clamp(1, 1000),
}
.validate()?;

fn valid_pty(rows: i32, cols: i32) -> bool {
    (1..=1000).contains(&rows) && (1..=1000).contains(&cols)
}
// call before issuing the shell request:
// assert!(valid_pty(rows, cols), "terminal size must be 1..=1000");

When it happens

Trigger: Calling shell tool code paths that construct a PtyDimensions (or accept rows/cols from the caller/request) where rows or cols is 0, negative, or greater than 1000, then calling validate().

Common situations: A client or LLM tool call supplies `rows: 0` or omits/JSON-encodes a bad default for terminal size; a caller converts a window size using unsigned arithmetic that underflows to 0; a serialized dimensions struct from an older client carries out-of-range values.

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

• Invalid pet PCM range.
• Invalid pet voice.
• open_application needs a plain executable/desktop name
• 1
• A pinned task provider requires an explicit model

AI-assisted analysis of Hmbown/CodeWhale@73e0f67d83 (2026-09-22). Data as JSON: /api/errors/90e6e98d3fb1fe02. Report an issue: GitHub.

Appendix: source

Thrown at crates/tui/src/tools/shell.rs:983

/// Cell dimensions accepted by the existing PTY owner. Pixel sizes remain
/// unspecified; callers must not allocate an unbounded terminal grid.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct PtyDimensions {
    pub rows: u16,
    pub cols: u16,
}

impl Default for PtyDimensions {
    fn default() -> Self {
        Self { rows: 24, cols: 80 }
    }
}

impl PtyDimensions {
    pub fn validate(self) -> Result<Self> {
        anyhow::ensure!(
            (1..=1000).contains(&self.rows) && (1..=1000).contains(&self.cols),
            "PTY rows and columns must each be between 1 and 1000"
        );
        Ok(self)
    }
}

/// A background shell process being tracked
pub struct BackgroundShell {
    pub id: String,
    pub command: String,
    pub working_dir: PathBuf,
    pub status: ShellStatus,
    pub exit_code: Option<i64>,
    pub started_at: Instant,
    /// When the job reached a terminal status. A finished job reports the
    /// duration it finished with; without this, `started_at.elapsed()` kept
    /// growing and `/jobs` showed "2m 07s" for a 12-second command (#5478).

View on GitHub (pinned to 73e0f67d83)