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 persona 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 Persona Documents:
Add similar instructions to your persona 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. Verify Your AI Model Supports Actions
Ensure you're using an AI model that has "actions enabled." Models with actions can utilize tools like knowledge retrieval to access your uploaded files.
To check if your model supports actions:
Look for models labeled with actions capability
Models without actions enabled cannot access uploaded knowledge files
Switch to a compatible model 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 persona 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.