Common Issues

This troubleshooting guide will help you resolve common issues you might encounter while using Marketrix. Each issue includes detailed solutions and prevention tips.

​

Connection Issues

​

Connection Not Working

Problem: Your connection shows as “Error” or “Inactive” Symptoms:

• Connection status shows as “Error” or “Inactive”
• Agents linked to the connection don’t work
• Widget integrations don’t function

Solutions:

1. Check your website URL:
   • Verify the URL is correct and accessible
   • Test the URL in a browser
   • Ensure the website is online and working
2. Verify domain configuration:
   • Check that allowed domains are correct
   • Include both example.com and www.example.com
   • Remove any typos in domain names
3. Test connection accessibility:
   • Visit your website to ensure it’s accessible
   • Check for any website errors or issues
   • Verify the website loads correctly
4. Update connection settings:
   • Go to your connection settings
   • Update the URL if it has changed
   • Save the changes

Prevention:

• Keep your website URL up to date
• Regularly check connection status
• Monitor your website for issues

​

Domain Not Allowed

Problem: Widget doesn’t work on your website Symptoms:

• Widget appears but doesn’t respond
• Error messages about domain restrictions
• Agent doesn’t work on your website

Solutions:

1. Check allowed domains:
   • Go to your connection settings
   • Verify your domain is in the allowed list
   • Include all variations of your domain
2. Add missing domains:
   • Add example.com and www.example.com
   • Include any subdomains you use
   • Add development and staging domains if needed
3. Test domain configuration:
   • Test the widget on your website
   • Verify it works on all pages
   • Check different domain variations

Prevention:

• Include all domain variations when setting up
• Regularly review and update domain lists
• Test on all domains you use

​

Agent Issues

​

Agent Not Responding

Problem: Your agent doesn’t respond to messages Symptoms:

• Agent doesn’t respond to questions
• Widget shows no response
• Playground testing fails

Solutions:

1. Check agent status:
   • Verify the agent is active
   • Check that the agent is properly configured
   • Ensure the agent is linked to a connection
2. Verify knowledge assignment:
   • Check that knowledge is assigned to the agent
   • Ensure knowledge is linked to the correct connection
   • Verify knowledge is processed and ready
3. Test agent instructions:
   • Review agent instructions for clarity
   • Ensure instructions are complete and specific
   • Test with simple questions first
4. Check connection status:
   • Verify the connection is active
   • Test the connection independently
   • Ensure the connection is properly configured

Prevention:

• Test agents thoroughly before deploying
• Keep agent instructions up to date
• Monitor agent performance regularly

​

Agent Gives Generic Responses

Problem: Agent provides vague or unhelpful answers Symptoms:

• Agent gives generic responses
• Responses don’t reference your knowledge
• Agent doesn’t provide specific information

Solutions:

1. Improve agent instructions:
   • Make instructions more specific
   • Include more business context
   • Add examples of good responses
2. Add more knowledge:
   • Upload additional documents
   • Add more videos
   • Include missing information
3. Test knowledge integration:
   • Verify knowledge is properly assigned
   • Test with questions that should use your knowledge
   • Check that knowledge is processed correctly
4. Refine agent behavior:
   • Update instructions based on testing
   • Add more specific guidance
   • Include better examples

Prevention:

• Write detailed, specific instructions
• Provide comprehensive knowledge
• Test agents thoroughly

​

Agent Tone Doesn’t Match Brand

Problem: Agent sounds too formal/casual for your business Symptoms:

• Agent tone doesn’t match your brand
• Responses sound generic or inappropriate
• Agent doesn’t reflect your company personality

Solutions:

1. Update agent instructions:
   • Adjust the tone and style in instructions
   • Include your brand personality
   • Add specific language guidelines
2. Change agent voice:
   • Switch between male and female voice
   • Test different voice options
   • Choose the voice that best matches your brand
3. Refine agent personality:
   • Update instructions to reflect your brand
   • Include specific personality traits
   • Add examples of appropriate responses

Prevention:

• Define your brand voice clearly
• Test different personality options
• Regularly review and update instructions

​

Knowledge Base Issues

​

Knowledge Not Processing

Problem: Documents or videos show as “Processing” for a long time Symptoms:

• Knowledge shows as “Processing” status
• Agent can’t access the knowledge
• Upload appears to be stuck

Solutions:

1. Check file format:
   • Verify the file format is supported
   • Check file size limits
   • Ensure the file is not corrupted
2. Try re-uploading:
   • Delete the stuck knowledge item
   • Re-upload the file
   • Wait for processing to complete
3. Check file size:
   • Ensure file is within size limits
   • Try uploading a smaller version
   • Compress large files if needed
4. Contact support:
   • If the issue persists, contact support
   • Provide details about the file and issue
   • Include any error messages

Prevention:

• Use supported file formats
• Keep files within size limits
• Test uploads with small files first

​

Agent Doesn’t Use Knowledge

Problem: Agent doesn’t reference your uploaded content Symptoms:

• Agent doesn’t mention your documents
• Responses don’t include your information
• Agent can’t answer questions about your content

Solutions:

1. Check knowledge assignment:
   • Verify knowledge is assigned to the agent
   • Ensure knowledge is linked to the correct connection
   • Check that the agent is linked to the same connection
2. Test knowledge relevance:
   • Ask questions that should use your knowledge
   • Check that knowledge content is relevant
   • Ensure knowledge is up-to-date
3. Improve knowledge organization:
   • Use clear titles and descriptions
   • Organize knowledge by topic
   • Include relevant keywords
4. Update agent instructions:
   • Tell the agent to use your knowledge
   • Provide examples of how to use knowledge
   • Include guidance on knowledge usage

Prevention:

• Assign knowledge properly to agents
• Keep knowledge organized and relevant
• Test knowledge integration thoroughly

​

Poor Search Results

Problem: Agent can’t find relevant information in knowledge Symptoms:

• Agent can’t answer questions about your content
• Search results are irrelevant
• Agent doesn’t find the right information

Solutions:

1. Improve knowledge structure:
   • Use clear headings and sections
   • Organize information logically
   • Include relevant keywords
2. Add more specific content:
   • Include more detailed information
   • Add specific examples
   • Provide comprehensive coverage
3. Update knowledge titles:
   • Use descriptive, searchable titles
   • Include relevant keywords
   • Make titles clear and specific
4. Test knowledge search:
   • Ask questions that should find your knowledge
   • Check that search results are relevant
   • Improve content based on search results

Prevention:

• Structure knowledge well
• Use clear, searchable titles
• Include relevant keywords

​

Widget Integration Issues

​

Widget Not Appearing

Problem: Widget doesn’t show up on your website Symptoms:

• Widget doesn’t appear on your website
• No chat interface is visible
• Integration code doesn’t work

Solutions:

1. Check integration code:
   • Verify the code is correctly placed
   • Ensure the code is before the closing </body> tag
   • Check for any syntax errors
2. Verify script URL:
   • Test the script URL in a browser
   • Ensure the URL is accessible
   • Check for any network issues
3. Check browser console:
   • Open browser developer tools
   • Look for JavaScript errors
   • Check for any error messages
4. Test on different browsers:
   • Try different web browsers
   • Check for browser-specific issues
   • Verify compatibility

Prevention:

• Test integration code thoroughly
• Check for JavaScript errors
• Verify compatibility across browsers

​

Widget Not Responding

Problem: Widget appears but doesn’t respond to messages Symptoms:

• Widget opens but doesn’t respond
• Messages don’t get sent
• No agent responses

Solutions:

1. Check agent status:
   • Verify the agent is active
   • Ensure the agent is properly configured
   • Test the agent in the playground
2. Verify integration configuration:
   • Check that the integration is properly set up
   • Ensure the agent is linked to the integration
   • Verify connection settings
3. Test network connectivity:
   • Check your internet connection
   • Verify the widget can connect to servers
   • Test with different networks
4. Check browser settings:
   • Ensure JavaScript is enabled
   • Check for any browser restrictions
   • Try disabling browser extensions

Prevention:

• Test integrations thoroughly
• Monitor agent and connection status
• Check network connectivity

​

Widget Appearance Issues

Problem: Widget doesn’t match your brand or looks wrong Symptoms:

• Widget colors don’t match your brand
• Widget size or position is wrong
• Widget doesn’t look professional

Solutions:

1. Check widget customization:
   • Review widget appearance settings
   • Verify colors and styling
   • Check size and position settings
2. Update widget settings:
   • Change colors to match your brand
   • Adjust size and position
   • Update styling and appearance
3. Test on different devices:
   • Check appearance on desktop
   • Test on mobile devices
   • Verify responsive design
4. Review brand guidelines:
   • Ensure widget matches your brand
   • Use consistent colors and fonts
   • Maintain professional appearance

Prevention:

• Set up widget customization properly
• Test appearance on different devices
• Follow brand guidelines

​

Performance Issues

​

Slow Response Times

Problem: Agent responses are slow or delayed Symptoms:

• Agent takes a long time to respond
• Widget appears unresponsive
• Users experience delays

Solutions:

1. Check network connectivity:
   • Verify your internet connection
   • Test with different networks
   • Check for network issues
2. Monitor server performance:
   • Check Marketrix server status
   • Look for any service issues
   • Contact support if needed
3. Optimize agent configuration:
   • Review agent instructions
   • Check knowledge base size
   • Optimize agent settings
4. Test with different browsers:
   • Try different web browsers
   • Check for browser-specific issues
   • Verify compatibility

Prevention:

• Monitor performance regularly
• Optimize agent configuration
• Check network connectivity

​

High Resource Usage

Problem: Widget or agent uses too many resources Symptoms:

• Website becomes slow
• Browser becomes unresponsive
• High CPU or memory usage

Solutions:

1. Check widget configuration:
   • Review widget settings
   • Optimize widget behavior
   • Check for unnecessary features
2. Monitor resource usage:
   • Check browser developer tools
   • Monitor CPU and memory usage
   • Look for performance bottlenecks
3. Optimize agent settings:
   • Review agent configuration
   • Check knowledge base size
   • Optimize agent behavior
4. Test on different devices:
   • Check performance on different devices
   • Test with different browsers
   • Verify compatibility

Prevention:

• Monitor resource usage
• Optimize configurations
• Test on different devices

​

Getting Help

​

When to Contact Support

Contact support if:

• You’ve tried all troubleshooting steps
• The issue persists after following solutions
• You encounter error messages you don’t understand
• You need help with advanced configuration

Before contacting support:

• Document the issue clearly
• Note what you’ve already tried
• Include any error messages
• Provide relevant details

​

Support Resources

Available support:

• Email support: support@marketrix.ai
• Documentation: This troubleshooting guide
• Community forums: User community and discussions
• Knowledge base: Additional help articles

What to include in support requests:

• Clear description of the issue
• Steps to reproduce the problem
• What you’ve already tried
• Any error messages or screenshots

​

Prevention Tips

​

Regular Maintenance

Perform regular maintenance:

• Check connection status regularly
• Monitor agent performance
• Review knowledge base quality
• Test integrations periodically

Keep things updated:

• Update agent instructions
• Refresh knowledge content
• Monitor widget performance
• Check for new features

​

Best Practices

Follow best practices:

• Test everything thoroughly
• Keep configurations simple
• Monitor performance regularly
• Document your setup

Stay informed:

• Read documentation updates
• Check for new features
• Monitor system status
• Join community discussions

​

Next Steps

After resolving issues, you’re ready to:

1. Continue with your setup - Complete your Marketrix configuration
2. Test your agents - Verify everything works correctly
3. Deploy your integrations - Go live with your agents
4. Monitor performance - Track usage and effectiveness

Most issues can be resolved by following the troubleshooting steps in this guide. If you continue to experience problems, don’t hesitate to contact support for additional help.

​

Getting Help

If you need assistance with troubleshooting:

• Check this guide for common issues and solutions
• Review documentation for detailed information
• Test systematically to identify problems
• Contact support for additional help

You’re now equipped to troubleshoot common issues and keep your Marketrix setup running smoothly! 🚀