What causes "Match n°{nth_result} not found (only {len(elements)} matches found)" in huggingface/smolagents?

First call with nth_result=1 and read the reported match count, then request a valid index

huggingface/smolagents · error · Exception

Match n°{nth_result} not found (only {len(elements)} matches

Error message

Match n°{nth_result} not found (only {len(elements)} matches found)

What it means

search_item_ctrl_f in smolagents' browser tools counts page elements containing the text via XPath contains(), and if nth_result exceeds the number of matches, raises this generic Exception naming the requested occurrence and the actual match count.

Source

Thrown at src/smolagents/vision_web_browser.py:116

        return f"'{s}'"
    if '"' not in s:
        return f'"{s}"'
    parts = s.split("'")
    return "concat(" + ', "\'", '.join(f"'{p}'" for p in parts) + ")"


@tool
def search_item_ctrl_f(text: str, nth_result: int = 1) -> str:
    """
    Searches for text on the current page via Ctrl + F and jumps to the nth occurrence.
    Args:
        text: The text to search for
        nth_result: Which occurrence to jump to (default: 1)
    """
    escaped_text = _escape_xpath_string(text)
    elements = driver.find_elements(By.XPATH, f"//*[contains(text(), {escaped_text})]")
    if nth_result > len(elements):
        raise Exception(f"Match n°{nth_result} not found (only {len(elements)} matches found)")
    result = f"Found {len(elements)} matches for '{text}'."
    elem = elements[nth_result - 1]
    driver.execute_script("arguments[0].scrollIntoView(true);", elem)
    result += f"Focused on element {nth_result} of {len(elements)}"
    return result


@tool
def go_back() -> None:
    """Goes back to previous page."""
    driver.back()


@tool
def close_popups() -> str:
    """
    Closes any visible modal or pop-up on the page. Use this to dismiss pop-up windows! This does not work on cookie consent banners.
    """

View on GitHub (pinned to 30bb116109)

Solutions

First call with nth_result=1 and read the reported match count, then request a valid index
Scroll or paginate to load all content before searching for later occurrences
Wait for the page/dynamic content to finish loading (WebDriverWait) before searching
Have the agent treat this error as a signal to re-search or navigate

Example fix

# before
search_item_ctrl_f(driver, 'pricing', nth_result=7)

# after
res = search_item_ctrl_f(driver, 'pricing', nth_result=1)  # 'Found 3 matches'
search_item_ctrl_f(driver, 'pricing', nth_result=min(7, 3))

Defensive patterns

Strategy: validation

Validate before calling

def count_matches(driver, text):
    from selenium.webdriver.common.by import By
    escaped = text.replace('\"', '\\"') if '\"' in text else f\"'{text}'\"
    return len(driver.find_elements(By.XPATH, f'//*[contains(text(), {escaped])]'))

if nth <= count_matches(driver, text):
    search_item_ctrl_f(driver, text, nth_result=nth)

Try / catch

try:
    search_item_ctrl_f(driver, text, nth_result=n)
except Exception as e:
    if 'not found' in str(e):
        # re-search with nth_result=1 to learn the count, then proceed
        raise

Prevention

Probe with nth_result=1 and parse the reported match count
Scroll/wait for lazy-loaded content before searching later matches
Clamp nth to the known match count

When it happens

Trigger: Calling search_item_ctrl_f(driver, text, nth_result=5) when only 3 elements on the page contain the text; agent assuming more occurrences exist than the page has.

Common situations: Paginated or lazily loaded content where later matches appear only after scrolling; dynamic pages whose content changed between navigation and search; off-by-one requests from the LLM (asking for n+1).

Related errors

AI-assisted analysis of huggingface/smolagents@30bb116109 (2026-08-28). Data as JSON: /api/errors/d7b0018765f6507a. Report an issue: GitHub.