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 Runs failing

When a QA Run reports problems, start with the verdict on each affected Journey:

• Failed — The persona didn’t reach the Journey’s expected outcome. This usually points to a real issue in the application, but can also mean the Journey is out of date.
• Indecisive — Marketrix couldn’t conclusively pass or fail the Journey. You can resolve an indecisive verdict manually, and Marketrix remembers your resolution for that application.

Common causes and what to do:

• UI changes — The application changed since the Journey was generated. Edit the Journey on the flow’s detail page, or regenerate the flow’s Journeys against the current UI.
• Changed expected outcome — The behavior changed intentionally. Update the Journey’s expectation so it matches what the application should now do.
• Slow or unresponsive app — The application was too slow during the run. Check application performance and re-run.
• Environment issues — The application couldn’t be reached or a login failed. Confirm the application URL is publicly reachable and that the configured credentials are valid.

See QA Flows Overview for verdict categories and how runs are evaluated.

Tip

After deploying UI changes, run your QA Flows to catch regressions early. Edit or regenerate Journeys when the UI changes so they keep matching your application.