Errors & troubleshooting

Quick fixes for the most common setup and automation problems.
Docs updated: 2025-12-17

Common errors

ErrorMeaningFix
EXT_NOT_DETECTEDThe page-side helper cannot detect the extension.Install/enable the extension, then call RTOForm.detect(). Also verify RTO_form_api.js is loaded.
DOMAIN_NOT_ALLOWEDThe host is not allow-listed.Add the host to the allow-list (see Allow-list).
NO_CONTROLLED_TABNo controlled tab exists for the tabKey.Call openTab first (or adopt an existing tab). Verify the tabKey you use.
TAB_NOT_FOUNDThe tabKey does not match any currently controlled tab.Use listTabs (or RTOTabsList) to see active keys.
ELEMENT_NOT_FOUNDThe selector did not match any element in the controlled tab.Use a more stable selector and call waitForSelector before the action.
TIMEOUTNo response was received in time.Increase timeoutMs and/or use waitForSelector and retries.
INVALID_URLA URL was missing, malformed, or not allowed.Use a full URL (example: https://example.com).
INVALID_HOSTA host value is missing or malformed.Use only the host (example: example.com), not a full URL.
UNKNOWN_ACTIONA DOM command action name was not recognized.Check spelling of the action. Make sure you are using helpers that match your extension version.
PROTECTED_ELEMENTThe element exists but cannot be interacted with.Some pages block automation for security. Try a different selector, or avoid protected UI elements.
EXECUTION_ERRORThe command failed inside the controlled tab.Check the target page state and run the action after waitForSelector.

Debug steps (fast)

  1. Detect: call RTOForm.detect(). If this fails, stop here.
  2. Allow-list: confirm the host is allowed (or add it).
  3. Controlled tab: call openTab and verify the tabKey exists in listTabs.
  4. Selector: use waitForSelector before any interaction.

Copy/paste debug snippet

// Minimal debug checklist
(async function(){
  try{
    await RTOForm.detect(1500);
    console.log("✅ detected");

    const tabs = await RTOForm.listTabs({}, { timeoutMs: 4000 });
    console.log("tabs:", tabs);
  }catch(e){
    console.error("RTO debug error:", e);
  }
})();

Next