Troubleshooting
Solutions for common issues encountered when using Magic Documents Import. If you cannot find a solution here, contact our support team at support@bc-magic.com.
Document Could Not Be Processed
Error: "The document could not be processed. Please check the file format and try again."
Possible causes and solutions:
Unsupported file format
Verify the file is a supported format (PDF, XML, CSV, JPEG, PNG, TIFF, EML, MSG). Check the file extension is correct and not renamed. Word documents (.docx) and Excel files (.xlsx) are not directly supported — export or save as PDF first.
Corrupted or password-protected PDF
Open the PDF in a viewer to confirm it is readable. Password-protected PDFs cannot be processed — remove the password protection and re-upload. Scanned PDFs with extremely low resolution (below 150 DPI) may also fail.
File size exceeds limit
The maximum file size is 25 MB per document. For large scanned documents, reduce the scan resolution or split into smaller files.
Extension is disabled
Verify that the Enabled toggle is set to Yes in Magic Documents Import Setup. Also check that your license key is valid and has not expired.
No Data Extracted
Error: "Document was processed but no data could be extracted."
Possible causes and solutions:
Poor image quality
For scanned documents and images, ensure the scan quality is at least 200 DPI. Blurry, skewed, or low-contrast images significantly reduce OCR accuracy. Re-scan the document with higher quality settings.
Unsupported document language
Check the Document Language setting in configuration. If your documents are in a language not set as the primary, switch to Auto-Detect mode or add the specific language.
Non-standard document layout
Highly customized or non-standard invoice layouts may not be recognized on the first attempt. Contact support@bc-magic.com to have a custom extraction template created for your vendor.
Image-only PDF without text layer
Some older scanners produce PDFs without a text layer. Ensure the OCR engine is enabled in settings. Consider upgrading to Azure AI Document Intelligence for better image-based extraction.
Vendor Not Found
Warning: "Could not match vendor. Please select a vendor manually."
Possible causes and solutions:
New vendor not yet in BC
If this is a new vendor, create the vendor record in Business Central first, then re-process the document. Ensure the vendor card has the VAT Registration No. filled in for future automatic matching.
Vendor name mismatch
The vendor name on the invoice may differ from the Business Central record (e.g., "Microsoft Corp" vs. "Microsoft Corporation"). Add a manual mapping rule in the Vendor Mapping configuration to handle this variation.
Missing VAT number on vendor card
VAT Registration No. is the most reliable matching method. Ensure your vendor cards have the VAT number filled in. Open the vendor card and enter the VAT Registration No. under the Invoicing tab.
Manual assignment and learning
Select the correct vendor manually in the review page. Enable the "Remember this mapping" option so that future documents from the same source are matched automatically.
Email Processing Issues
Email Not Detected
Issue: Emails sent to the import mailbox are not appearing in the Document Import Worksheet.
Email polling is disabled
In Magic Documents Import Setup, verify that the Incoming Email Address is configured and the email polling interval is set. Click Test Connection to confirm mailbox access.
Authentication expired
OAuth2 tokens may expire. Go to the Email Processing tab in Setup and click Re-authenticate. For Microsoft 365, ensure the app registration in Azure AD still has the required permissions.
Emails are in a subfolder
By default, Magic Documents Import only monitors the Inbox folder. If emails are routed to a subfolder via mail rules, update the Monitored Folder setting in configuration.
Attachment Not Supported
Warning: "Attachment type not supported. Skipping file: document.docx"
Unsupported attachment format
Only PDF, XML, CSV, JPEG, PNG, and TIFF attachments are processed. Word (.docx), Excel (.xlsx), and ZIP files are skipped. Ask vendors to send invoices in PDF format, or convert files before uploading manually.
Inline images vs. attachments
Images embedded directly in the email body (inline) are not processed as attachments. Only files explicitly attached to the email are extracted. Ask the sender to attach the invoice as a separate file.
Connection Problems
Error: "Failed to connect to email server. Check your credentials and network settings."
Firewall or network restrictions
Ensure your Business Central server can reach the email server. For Microsoft 365, outbound HTTPS (port 443) to graph.microsoft.com must be allowed. For IMAP, port 993 must be open.
Incorrect credentials
Double-check the email address and password. For OAuth2 authentication, verify the client ID, tenant ID, and client secret in the Azure AD app registration. Ensure Mail.Read and Mail.ReadWrite API permissions are granted.
Multi-factor authentication blocking access
Basic authentication with MFA-enabled accounts will fail. Use OAuth2 / Microsoft Graph API authentication instead, or create an app password for the service account if your organization policy allows it.
Performance Issues
Slow document processing
OCR processing of scanned documents is more resource-intensive than text-based PDFs or XML. Consider these optimizations:
- Use native/digital PDFs instead of scanned images when possible
- Reduce scan resolution to 200-300 DPI (higher DPI does not improve accuracy significantly)
- Process large batches during off-peak hours
- Upgrade to Azure AI Document Intelligence for faster cloud-based OCR
Large file processing
Documents over 10 MB take longer to process. For large multi-page scans, consider splitting them into individual invoices. The maximum supported file size is 25 MB per document.
Permission Errors
"You do not have permission to access this page"
The user does not have the required MDI permission set. An administrator must assign MDI-USER (for processing) or MDI-ADMIN (for configuration) via the user's Permission Sets page in Business Central.
"You do not have permission to create purchase invoices"
The user has MDI permissions but lacks the standard Business Central permissions to create purchase documents. Ensure the user also has the appropriate BC permission sets (e.g., D365 PURCH DOC, EDIT).
"License key is invalid or expired"
Verify your license key in Magic Documents Import Setup. If it has expired, contact support@bc-magic.com to renew your license. During the renewal period, the extension operates in read-only mode.
Getting Help
If you cannot resolve your issue using the solutions above, our support team is here to help:
Tip: When contacting support, include the following information to speed up resolution: your Business Central version, Magic Documents Import version (found in Extension Management), a description of the issue, screenshots or error messages, and the diagnostic report (see below).
Diagnostic Tools
Magic Documents Import includes built-in diagnostic tools to help identify and resolve issues:
Processing Log
Search for MDI Processing Log to view a detailed log of all document processing activities. Each entry includes timestamps, status, error messages, and processing duration.
Email Processing Log
Search for MDI Email Log to see all email polling activity, including connection attempts, emails received, attachments extracted, and any errors.
Diagnostic Report
In Magic Documents Import Setup, click Actions > Generate Diagnostic Report. This creates a comprehensive report including your configuration settings, recent processing statistics, error summary, and system information. Share this report with BC-Magic support for faster troubleshooting.
Test Document Processing
Use Actions > Test Processing to process a sample document with verbose logging enabled. This provides detailed step-by-step output showing exactly how the document is analyzed, what data is extracted, and where any failures occur.