Skip to main content

Troubleshooting

Under Review

This article is currently under review. Some content may be incomplete or inaccurate.

Common issues and solutions when working with DocAI Fabric.

Classification Problems​

Documents Always Classified as "Unknown"​

Symptoms: All or most documents get the "Unknown" class despite having defined classes.

Solutions:

  1. Check class descriptions are detailed enough, including key identifying features
  2. Ensure classes cover the document types you're uploading
  3. Verify descriptions mention distinguishing characteristics (headers, logos, specific sections)
  4. Review confidence thresholds in project settings
tip

Ask the AI Assistant: "Show me my current document classes and their descriptions" to quickly review your setup.

Wrong Classification​

Symptoms: Documents are assigned to incorrect classes.

Solutions:

  1. Make class descriptions more distinct, emphasizing unique features of each class
  2. Add distinguishing features to each class (e.g., "Invoices always have line items and a total due")
  3. Review similar classes for overlapping descriptions
  4. Reclassify affected documents manually and review the results

Low Classification Confidence​

Symptoms: Documents are classified correctly but with low confidence scores.

Solutions:

  1. Add more detail to class descriptions
  2. Include format-specific hints (e.g., "typically a single-page document with a table")
  3. Ensure each class is clearly different from other classes

Extraction Problems​

Missing Field Values​

Symptoms: Fields return empty or null when data exists in the document.

Solutions:

  1. Improve field descriptions with more context about what to look for
  2. Add location hints: "Usually found in the top-right corner of the first page"
  3. Specify expected format: "Date in format MM/DD/YYYY"
  4. Check if the field type matches the data (e.g., use date type for dates, not text)

Incorrect Field Values​

Symptoms: Wrong data extracted for fields.

Solutions:

  1. Make field descriptions more specific about what to extract
  2. Clarify what NOT to extract (e.g., "The invoice total, not the subtotal or tax")
  3. Check for similar fields that might confuse the AI
  4. Verify the field type is appropriate

Repeating Groups Not Detected​

Symptoms: Tables or line items not properly extracted as groups.

Solutions:

  1. Ensure the group is defined as a repeating type
  2. Add column/field descriptions for each table column
  3. Describe the table structure in the group description
  4. Check if table format varies across documents

Processing Issues​

Transaction Stuck in "Processing"​

Symptoms: Status stays at "processing" for an extended time.

Solutions:

  1. Check status.docaifabric.com for any ongoing incidents
  2. Check if the processing queue is running
  3. Review error logs for failures
  4. Verify Azure OpenAI endpoint connectivity
  5. Check for resource limits (memory, API quotas, rate limits)

Failed Transactions​

Symptoms: Transaction status shows "failed".

Solutions:

  1. Check file format is supported (PDF, JPEG, PNG, TIFF)
  2. Verify the file is not corrupted
  3. Ensure file size is within limits
  4. Review error messages in the transaction detail view

Connection Issues​

Before diving into configuration, check status.docaifabric.com to rule out an ongoing service incident.

If you see API authentication errors (401/403):

  1. Verify your API key is valid
  2. Check tenant/project access permissions
  3. Ensure your session is active (for the web interface)
  4. Refresh authentication if expired

Best Practices​

Writing Good Field Descriptions​

The field description is the most important factor for extraction quality:

  • Be specific: "The unique invoice identifier, usually starting with 'INV-'"
  • Include location hints: "Usually found in the top-right corner of the first page"
  • Mention format: "Date in format MM/DD/YYYY"
  • Clarify ambiguity: "The total amount due including tax, not the subtotal"

Writing Good Class Descriptions​

  • Include key identifying features: "Invoices from vendors requesting payment, typically showing line items, totals, and payment terms"
  • Mention distinguishing characteristics: "Receipts showing proof of purchase with date and amount paid"
  • Be specific enough to differentiate from similar classes

Testing Changes​

  1. Make one change at a time
  2. Test with sample documents after each change
  3. Compare before/after extraction results
  4. Roll back if quality decreases

Regular Maintenance​

  1. Review low-confidence classifications periodically
  2. Update field and class descriptions based on common errors
  3. Monitor the processing queue for backlogs