Common Issues and Debugging Tips
This guide covers common issues you might encounter when working with AI agents in MindPal and how to resolve them.
Context and Continuity Issues
Out of Context Length
Issue: Your agent encounters an error about context length being exceeded. This happens when the conversation history, the agent’s Always files and system instructions combined exceed the model’s maximum context window.
Symptoms:
- Error message mentioning “context length” or “token limit”
- Agent stops responding mid-conversation
- Truncated or incomplete responses
Solutions:
-
Switch to a model with a larger context window:
- Hover a model in the model picker to see its context window
- Gemini models offer the largest context windows
-
Read less in every reply:
- In the agent’s Knowledge tab, switch long files from Always to On demand, and keep the meter under about 6,000 words
- Give the agent only the folders its job needs
-
Optimize system instructions:
- Keep instructions concise but clear
- Remove redundant or repetitive instructions
Agent Doesn’t Remember Previous Conversations
Issue: Your agent seems to forget what was discussed earlier in the conversation.
Solutions:
- Check session continuity - Ensure you’re using the same conversation session
- Write it down in Knowledge - Agents don’t save notes for themselves. Put what should carry across conversations in a document in Knowledge and give it to the agent
- Enable Custom User ID - For chatbots, use Custom User ID to maintain conversation history
Response Quality Issues
Poor Answer Quality
Issue: The agent’s responses are vague, generic, or don’t meet your expectations.
Solutions:
-
Upgrade the model:
- Try a Recommended model with more credits per request, such as the latest Claude Opus or GPT
- For writing and coding, Claude models are a strong choice; for complex reasoning, the latest GPT and Claude Opus models
- See AI Credits for every model and its cost
-
Improve system instructions:
- Be specific about the expected output format
- Include examples of good responses
- Define clear constraints and guidelines
-
Lower temperature for more consistent, focused responses
-
Give it your material through Knowledge
Agent Gives Inconsistent Responses
Issue: The same question produces different answers each time.
Solutions:
- Lower the temperature setting (closer to 0 = more deterministic)
- Add more specific instructions in the system prompt
- Use examples to demonstrate desired output format
Agent Ignores Instructions
Issue: The agent doesn’t follow your system instructions.
Solutions:
- Check instruction clarity - Avoid contradictory or ambiguous rules
- Move critical instructions to the top of the system prompt
- Use explicit formatting:
IMPORTANT: Always do X before Y. NEVER do Z. - Reduce instruction complexity - Too many rules can confuse the model
Knowledge Issues
Agent Doesn’t Use Your Files
Issue: You added files to Knowledge, but the agent answers as if it hasn’t seen them.
Solutions:
- Check the agent has them - Open the agent’s Knowledge tab. A file in Knowledge is only used by the agents it’s given to. A file’s own page shows which agents use it under Used by
- Save the agent - Changes in the Knowledge tab apply once you update the agent
- Check the file was read - Open the file. If it shows a problem instead of what agents read, follow what it says. See When a file can’t be read yet
- Name and describe it plainly - With On demand, the agent decides what to open from file names and descriptions. A file called
scan_0042.pdfwith no description is easy to miss;Refund policyisn’t - Use Always for must-follow rules - If the agent should apply a file in every reply, set it to Always
Answers Don’t Match Your Material
Issue: The agent gives information that doesn’t match your files.
Solutions:
- Remove outdated versions - If two files say different things, the agent may use either. Replace the old one or move it to the Trash
- Point to the right file - Mention it with
@in the agent’s instructions, saying when to use it - Refresh web pages - An imported page is saved as it was. Click Refresh on it when the page changes
- Check what agents read - On a file’s page, What agents read shows the text agents get. Scanned pages or images of text may have none
File Can’t Be Read
Issue: A file in Knowledge shows a problem instead of its contents.
Solutions:
- Follow the message on the file - It says what went wrong and what to do
- Check the size - Files over 200 MB aren’t read. Split them, or upload a smaller version
- Use a readable format - PDF, Word, slides, spreadsheets and text work best. Scanned documents often have no text: upload a version with real text, or write the content as a document
Tool Issues
The Agent Doesn’t Use a Tool
Issue: The agent answers from what it knows instead of using a tool you expected it to use.
Solutions:
- Make sure the agent has the tool - In the agent’s Tools, a built-in tool must be switched on, and an app or service must be added with that tool switched on. Then press Update agent: changes only apply once saved
- Check the model - Some models can’t use tools. If the agent’s Tools section says so, pick another model in Language model
- Tell it when to use the tool in the system instructions:
Before answering a question about current events, use Web search. When a customer asks about an order, look it up with "Find order" first. - Describe your own tools clearly - For a link to call or an API, say in plain words when the agent should use it. See Teach the agent your own tools
- Give it fewer tools - With a long list to choose from, the agent picks less well. Switch off what this agent’s job doesn’t need. See Give each agent only what it needs
A Tool Step Failed
Issue: A step in the chat says the tool couldn’t do something, such as “Couldn’t search the web”.
Solutions:
- Open the step in a MindPal chat to see what the agent sent and what went wrong
- Check the connection - Go to Assets → Tools. If the app or service needs attention, it’s at the top with a Fix button
- Try your own tool directly - For a link to call or an API, Try it sends a real request so you can see the service’s answer
- Check the other side - The service may be down, or may have refused the request because of its own permissions or limits
A step that ends in “nothing found” didn’t fail: the tool worked but had nothing to return. Try a different request or source.
A Connection Stopped Working
Issue: An app or service shows Sign-in expired, Key refused or Not responding on Assets → Tools.
Why it happens: Sign-ins expire, keys get changed or revoked, and services go down. Until it’s fixed, every agent that uses the connection can’t use its tools.
Solutions:
- Sign-in expired - Press Fix and sign in again
- Key refused - Press Fix and paste a key that works, from the service’s settings
- Not responding - Wait a moment and try again. If it stays down, check whether the service changed its link, and reconnect with the new one
An MCP Link Won’t Connect
Issue: You pasted an MCP link, but MindPal doesn’t show any tools.
Solutions:
- Copy the link again from the service’s docs or settings, in case part of it was cut off
- Use the online version - MindPal connects to servers on the internet over Streamable HTTP. A server that only runs on your own computer can’t be connected
- Sign in or add a key if MindPal says the service asks for one
- Try again in a moment - The server may be down for a while
See Connect your apps and services.
An App Shows a Lock
Issue: Apps such as Gmail and Google Drive show a lock in the catalog.
Solution: Apps you connect by signing in need a paid plan. See Plans and credits.
Published Chatbot Issues
Chatbot Not Loading
Issue: Published chatbot doesn’t appear or load on your website.
Solutions:
- Check embed code - Ensure it’s correctly pasted in your HTML
- Verify domain restrictions - If set, your domain must be in the allowed list
- Check for JavaScript errors - Open browser console (F12) for error messages
- Clear browser cache - Old cached versions may cause issues
Custom Session Context Not Working
Issue: Personalization data isn’t being passed to the chatbot.
Solutions:
- Verify configuration - Ensure custom session context is enabled
- Check key names - Keys must match exactly (case-sensitive)
- Verify script order:
- Widget:
mindpalConfigmust be defined BEFORE loading the script - Iframe: Include the helper script with correct
data-target
- Widget:
- Check domain restrictions - Your domain must be allowed
Performance Issues
Slow Response Times
Issue: Agent takes too long to respond.
Solutions:
- Use faster models:
- Gemini 2.5 Flash (fastest)
- GPT-5 Mini
- Claude 4.5 Haiku
- Read less in every reply - Switch long files to On demand in the agent’s Knowledge tab
- Simplify system instructions - Shorter prompts process faster
- Check your internet connection
High Credit Consumption
Issue: Using more AI credits than expected.
Solutions:
- Use cost-effective models:
- Gemini 2.5 Flash: 1 credit
- DeepSeek V3/R1: 0.5 credits
- GPT-5 Nano: 1 credit
- Set output length limits - Restrict maximum tokens
- Review workflow efficiency - Each node consumes credits
- Use Gate Nodes to stop workflows early when inputs are invalid
Getting More Help
If these solutions don’t resolve your issue:
- Check the workflow common issues for workflow-specific problems
- Search our YouTube tutorials for video guides
- Join our Facebook Community to ask questions
- Contact support at support@mindpal.io