Fix: Vibium Timeout Errors

A Vibium timeout error means an element never became actionable within the wait window — by default 30 seconds — so the action raised an error instead of silently doing nothing. Vibium auto-waits before every click, type, or fill: it polls the element against its actionability checks (visible, stable, receiving events, enabled) and acts the instant they pass. A timeout therefore is not random flakiness; it is Vibium telling you the element was never ready. The four common causes are a selector that matches nothing, an element stuck display:none or disabled, an overlay (cookie banner, modal, spinner) intercepting the click, or a page that is genuinely slow. The fix is almost always to address the real cause rather than to crank the timeout higher. When a page really is slow, you can raise the per-action timeout. This guide walks through diagnosing and fixing each case in Python.

Why does Vibium throw a timeout error?

Vibium throws a timeout when its actionability poll never succeeds before the deadline. Before acting, Vibium runs a set of checks and retries them on a loop until either every required condition passes or the timeout elapses. For a click, the element must be visible, stable (its bounding box has stopped moving), receiving pointer events at its center, and enabled. If any required check keeps failing, the loop runs out of time and the action raises.

from vibium import browser_sync as browser
 
vibe = browser.launch()
vibe.go("https://example.com")
 
# Raises a timeout if #submit never becomes clickable in the window
vibe.find("#submit").click()
 
vibe.quit()

That explicit failure is the feature working as designed. A clear timeout points you at the cause far faster than a confusing no-op would.

How do I find the real cause of a timeout?

Start by checking which condition is failing, because the fix differs for each. The fastest diagnostic is to capture what the page actually looked like at the moment of failure.

try:
    vibe.find("#submit").click()
except Exception:
    png = vibe.screenshot(full_page=True)
    with open("/tmp/timeout.png", "wb") as f:
        f.write(png)
    raise

Open the screenshot and ask: Is the element even on screen? Is it greyed out (disabled)? Is a banner or modal sitting over it? Is a spinner still running? The answer tells you which of the sections below applies. For background on the checks themselves, see waiting and actionability.

How do I fix a wrong-selector timeout?

The most frequent cause is a selector that matches no element at all, so the poll never finds anything to check. Prefer semantic selectors that describe the element the way a user perceives it, rather than a brittle CSS path tied to page structure.

# Brittle: breaks when the DOM is reshuffled
vibe.find("div.form > button:nth-child(3)").click()
 
# Resilient: matches by role and visible label
vibe.find(role="button", text="Submit").click()

find() accepts role, text, label, placeholder, and testid, which survive markup churn that breaks positional CSS. See find element for the full set of options.

How do I fix an overlay or disabled-element timeout?

If a cookie banner, modal, or spinner covers your target, the receives-events check keeps failing because a hit-test at the element's center returns the overlay instead. Act on the blocker first, then on your real target — do not just add a sleep.

# Dismiss the overlay, then the real target becomes actionable
vibe.find(role="button", text="Accept").click()
vibe.find("#start-checkout").click()

If the element is genuinely disabled (greyed out until a form is valid), the enabled check will keep failing — fill the required fields first so the control becomes enabled, then click it.

How do I increase the Vibium timeout?

When a page is legitimately slow, raise the timeout for that one action by passing timeout in milliseconds. Reserve this for real slowness, not for masking a wrong selector.

# Wait up to 60 seconds for a slow dashboard to finish loading
vibe.find("#report-table").click(timeout=60000)

A higher timeout only helps when the element eventually becomes actionable. If the cause is a bad selector or a permanent overlay, a longer wait just delays the same failure.

Tips for avoiding timeouts

• Read the screenshot first — it tells you which check is failing in seconds.
• Use semantic selectors — role and text survive redesigns that break CSS paths.
• Clear blockers, not the clock — dismiss banners and modals instead of raising the timeout.
• Raise the timeout only for real slowness — it cannot fix a selector that matches nothing.

Next steps

• Fix: Vibium 'Element Not Found' errors
• Waiting and actionability in Vibium
• What is Vibium?