If you're experiencing issues with uploaded files or knowledge documents in Magai, this guide will help you troubleshoot common problems. Whether your files are stuck in "pending" status or the AI isn't using your uploaded documents as expected, follow these steps to resolve the issue.
Common Issues and Solutions
1. Check Your Document Status
First, verify the status of your uploaded document in either your workspace or Agent settings:
Pending Status: The document is still processing and not ready for use
Success Status: The document has been processed and is available for the AI to use
Failed Status: The upload or processing encountered an error
If your document shows "Pending":
Wait 2-5 minutes for processing to complete
If it remains pending longer than 5 minutes, the processing has likely failed (even if not explicitly labeled as failed)
Delete the file and try uploading again
If the issue persists after multiple attempts, contact our support team through the in-app support messenger
Once you've confirmed your document has processed successfully, the next step is ensuring the AI knows how to use it properly.
2. Add Clear Instructions for Document Usage
If your file shows "Success" status but the AI isn't using it, you need to provide explicit instructions telling the AI when, why, and how to use your uploaded documents.
For Workspace Documents:
Add instructions to your workspace custom context, such as:
You have been given access to these files: [list your file names]. You will use these files for the purpose of [specify the purpose, e.g., "answering questions about our company policies," "providing product information," etc.]. Reference these documents whenever users ask questions related to [specify relevant topics].
For Agent documents:
Add similar instructions to your Agent settings:
You have access to uploaded knowledge files containing [describe content]. Use these files when users ask about [relevant topics] or when you need to provide specific information about [subject matter].
Important: Don't leave document usage to chance. Always provide clear, specific instructions about:
When the AI should access the files
Why it should use them
How they should be referenced
What topics or questions they relate to
After setting up proper instructions, make sure you're using a compatible AI model that can actually access these files.
3. Use a model that can work with tools and files
Use a model that can work with tools and files. New chats start on Claude Sonnet 5. Switch models in the unified model picker if needed.
If you've verified all these settings and are still experiencing issues, there are a few additional factors to consider.
Additional Troubleshooting Tips
File Format: Ensure your documents are in supported formats
File Size: Check that your files aren't too large for processing
Content Quality: Make sure uploaded documents contain clear, readable text
Network Issues: If uploads fail repeatedly, check your internet connection
When all troubleshooting steps have been exhausted, it may be time to reach out for additional assistance.
When to Contact Support
Reach out to our support team through the in-app support messenger if files continue to fail processing after multiple attempts, you've followed all troubleshooting steps but issues persist, you're experiencing unusual errors or behaviors, or you need assistance with workspace or Agent configuration.
Following these troubleshooting steps should resolve most issues with uploaded files and knowledge documents. By ensuring proper file processing, providing clear instructions, and using compatible AI models, you'll be able to make the most of Magai's knowledge retrieval capabilities and enhance your AI interactions with your custom content.