Hmbown/CodeWhale · error · ValueError

overlap must be smaller than max_chars

Error message

overlap must be smaller than max_chars

What it means

chunk() raises ValueError when overlap >= max_chars; negative overlap is clamped to 0 before the comparison. After each chunk the loop sets start = end - overlap, so with overlap at or above the window size start would never advance and the loop would never terminate. This check is an infinite-loop guard, not a style rule.

Source

Thrown at crates/tui/src/repl/runtime.rs:897

        snippet_start = max(0, start - 120)
        snippet_end = min(len(_context), end + 120)
        hits.append({
            "index": i,
            "start": start,
            "end": end,
            "match": m.group(0),
            "snippet": _context[snippet_start:snippet_end],
        })
    return hits

def chunk(max_chars=20000, overlap=0):
    """Return full-coverage input chunks with index/start/end/text fields."""
    max_chars = int(max_chars)
    overlap = max(0, int(overlap))
    if max_chars <= 0:
        raise ValueError("max_chars must be > 0")
    if overlap >= max_chars:
        raise ValueError("overlap must be smaller than max_chars")
    chunks = []
    start = 0
    idx = 0
    total = len(_context)
    while start < total:
        end = min(total, start + max_chars)
        chunks.append({"index": idx, "start": start, "end": end, "text": _context[start:end]})
        idx += 1
        if end >= total:
            break
        start = end - overlap
    return chunks

def chunk_context(max_chars=20000, overlap=0):
    """Compatibility alias for chunk()."""
    return chunk(max_chars=max_chars, overlap=overlap)

def chunk_coverage(chunks):

View on GitHub (pinned to 8880682c63)

Solutions

1. Use a strictly smaller overlap, e.g. chunk(20000, 200)
2. Scale overlap as a fraction of the window: overlap = max_chars // 10
3. Keep overlap 0 when full coverage is the goal; chunks already cover the input end to end

Example fix

# before
chunk(max_chars=1000, overlap=1000)
# after
chunk(max_chars=1000, overlap=100)

max_chars = max(1, int(max_chars))
overlap = max(0, min(int(overlap), max_chars - 1))
chunks = chunk(max_chars, overlap)

try:
    chunks = chunk(max_chars, overlap)
except ValueError:
    chunks = chunk(max_chars, 0)  # overlap=0 always satisfies the guard

When it happens

Trigger: Calling chunk(1000, 1000), chunk(500, 5000), or generated code setting overlap equal to the window 'so nothing is missed'.

Common situations: LLM-generated recall-maximizing configs; argument order mixups after refactors; configs written for tools where overlap may equal the window size.

Related errors

• max_chars must be > 0
• unit must be 'chars' or 'lines'
• version must be a semantic release identifier
• max_turns must be between 1 and 10000
• disabled_tools must use Codewhale catalog identifiers: ${",

AI-assisted analysis of Hmbown/CodeWhale@8880682c63 (2026-08-16). Data as JSON: /api/errors/8b1e78a70540015b. Report an issue: GitHub.