Common Issues

Agent not responding

If your agent isn’t replying to messages in the widget:

• Check agent status — If the status shows “Learning”, the agent is still indexing knowledge. Wait for indexing to complete before testing.
• Verify knowledge is assigned — An agent without knowledge has no context to draw from. Assign at least one knowledge item.
• Check the application URL — Ensure the application URL is accessible. The agent uses this URL for simulations and contextual understanding.

Note

After assigning new knowledge, the agent needs a few minutes to process and index the content. Responses will improve once indexing 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.
• Check credentials — Confirm that mtx-id and mtx-key values match the ones in your widget settings.
• 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 error messages. Common errors include invalid API keys 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 accessible from the 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 properly in your application settings.

Caution

Simulations run in a cloud browser. URLs behind VPNs, firewalls, or localhost will not be accessible. Use a publicly reachable 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, DOCX, TXT, HTML, or MD.
• File size — Very large files may 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 content. Try refreshing the knowledge item to re-trigger the import.

QA tests failing

If QA test cases are failing:

• Review the failure category — Each failure 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 will attempt 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 is slow or unresponsive during testing. Check application performance and increase timeout thresholds if needed.
• Flow change failures — The application’s workflow has changed since the test was generated. Re-run the QA flow to generate updated test cases.

Tip

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