Common Issues

Widget not responding

If the widget isn’t replying to messages:

• Check learning status — If the Application shows a Learning status, Marketrix is still processing knowledge or simulation data. The widget can still respond, but may not have full context yet. Wait for processing to finish before testing.
• Verify Knowledge is present — A widget grounded in an empty Knowledge Base has little context to draw from. Add documents and videos so Marketrix understands your product. See Knowledge.
• Check the application URL — Ensure the application URL is accessible. Marketrix uses this URL for simulations and contextual understanding.

Note

After adding new Knowledge, Marketrix needs a little time to process and index the content. Responses improve once processing finishes.

Widget not appearing

If the widget doesn’t show up on your website:

• Script tag placement — Verify the script tag is placed before the closing </body> tag. See Widget Setup.
• Check credentials — Confirm that mtx-id and mtx-key match the Widget ID and API Key on your widget settings page.
• API host URL — Ensure mtx-api-host points to the correct environment (https://api.marketrix.co for production).
• Browser console — Open your browser’s developer tools and check the console for errors. Common causes include invalid credentials and network connectivity issues.
• Ad blockers — Some browser extensions may block the widget script. Test in an incognito window with extensions disabled.

Simulation fails immediately

If a simulation stops as soon as it starts:

• Application URL — Verify the URL is reachable from the public internet. Local or internal-only URLs cannot be reached by the simulation engine.
• Authentication — For apps that require login, confirm that the credentials configured in your application settings are correct.
• Allowed domains — Check that allowed domains are configured correctly in your application settings.

Caution

Simulations run in a cloud browser. URLs behind VPNs, firewalls, or localhost will not be reachable. Use a publicly accessible staging environment for testing.

Knowledge not processing

If a knowledge item is stuck or not processing:

• File format — Ensure files are in a supported format: PDF (.pdf), Word (.doc, .docx), plain text (.txt), or Markdown (.md). See Adding Documents.
• File size — Files can be up to 100 MB each. Very large files take longer to process; if a file seems stuck, try splitting it into smaller documents.
• URL imports — If importing from a URL, confirm the URL is publicly accessible and returns valid, fetchable content. Try re-adding the knowledge item to re-trigger the import.

QA tests failing

If QA test cases are failing, start with the failure category — each failed test is classified as one of locator, assertion, timeout, flow change, or environment:

• Locator failures — Usually indicate UI changes in your application. The self-healing feature attempts to find updated selectors automatically.
• Assertion failures — The expected result doesn’t match the actual result. Review whether the expected behavior has intentionally changed.
• Timeout failures — Suggest the application was slow or unresponsive during the run. Check application performance.
• Flow change failures — The application’s workflow has changed since the test was generated. Re-run the QA Flow to regenerate test cases against the current flow.
• Environment failures — The test couldn’t run because of an environment problem (for example, an unreachable URL or a failed login). Confirm the application is up and the configured credentials are valid.

See QA Flows Overview for how failures are categorized and how self-healing works.

Tip

After deploying UI changes, run your QA Flows to catch regressions early. Self-healing handles minor selector changes, but significant layout changes may require regenerating test cases.