SeleniumHQ/selenium · error · WebDriverException

To submit an element, it must be nested inside a form elemen

Error message

To submit an element, it must be nested inside a form element

What it means

Raised by WebElement.submit() when the executed JavaScript fails with a JavascriptException. The submit() atom walks up the element's parentNode looking for a <form> ancestor and dispatches a submit event; if no containing form is found, the JS throws 'Unable to find containing form element', which Python catches and re-wraps as this WebDriverException. So the message indicates the element is not nested inside a <form>.

Source

Thrown at py/selenium/webdriver/remote/webelement.py:138

            form = driver.find_element(By.NAME, "login")
            form.submit()
        """
        script = (
            "/* submitForm */var form = arguments[0];\n"
            'while (form.nodeName != "FORM" && form.parentNode) {\n'
            "  form = form.parentNode;\n"
            "}\n"
            "if (!form) { throw Error('Unable to find containing form element'); }\n"
            "if (!form.ownerDocument) { throw Error('Unable to find owning document'); }\n"
            "var e = form.ownerDocument.createEvent('Event');\n"
            "e.initEvent('submit', true, true);\n"
            "if (form.dispatchEvent(e)) { HTMLFormElement.prototype.submit.call(form) }\n"
        )

        try:
            self._parent.execute_script(script, self)
        except JavascriptException as exc:
            raise WebDriverException("To submit an element, it must be nested inside a form element") from exc

    def clear(self) -> None:
        """Clears the text if it's a text entry element.

        Example:
            text_field = driver.find_element(By.NAME, "username")
            text_field.clear()
        """
        self._execute(Command.CLEAR_ELEMENT)

    def get_property(self, name) -> str | bool | WebElement | dict:
        """Gets the given property of the element.

        Args:
            name: Name of the property to retrieve.

        Returns:
            The value of the property.

View on GitHub (pinned to aa36b38e69)

Solutions

Confirm the element is actually inside a <form>; if not, use element.click() on the submit button instead.
For non-form submission, trigger the action via the app's own JS (execute_script) rather than submit().
If the element should be in a form, wait for the form to render before calling submit().

Example fix

# before
btn = driver.find_element(By.ID, 'login-btn')  # not in a <form>
btn.submit()  # raises

# after
btn.click()  # or locate the actual <form> and submit that

Defensive patterns

Strategy: validation

Validate before calling

# Verify a form ancestor exists before calling submit()
tag = element.find_element(By.XPATH, 'ancestor::form[1]')
element.submit()

Type guard

def is_inside_form(element) -> bool:
    from selenium.webdriver.common.by import By
    try:
        element.find_element(By.XPATH, 'ancestor::form[1]')
        return True
    except Exception:
        return False

Try / catch

from selenium.common.exceptions import WebDriverException
try:
    element.submit()
except WebDriverException as e:
    if 'nested inside a form' in str(e):
        element.click()  # fall back to clicking

Prevention

Prefer element.click() on submit buttons for non-form SPAs.
Check for a form ancestor before calling submit().
Wait for the form to be present in dynamic pages.

When it happens

Trigger: Calling element.submit() on an element (button, div, input) that has no <form> ancestor in the DOM. The JS loop `while (form.nodeName != 'FORM' && form.parentNode)` exhausts parentNode without finding a FORM.

Common situations: Modern SPAs that use JS handlers instead of real <form> elements, or clicking a submit-like button outside any form. Also when the element is detached/stale so parentNode is null.

Related errors

AI-assisted analysis of SeleniumHQ/selenium@aa36b38e69 (2026-08-14). Data as JSON: /api/errors/4dd55e91c3758c17. Report an issue: GitHub.