Skip to main content
This guide covers common issues you might encounter when working with Dex and how to resolve them.

Installation Issues

Installing the Dex SDK

Your Scale team provides the dex-sdk package and the dex-core and data-sources-core packages it depends on. Install them as described in Getting Started with Dex. Verify installation:

Common Installation Errors

Package Not Found pip can’t install dex-sdk, dex-core, or data-sources-core from PyPI. Install all three from the files or package index URL your Scale team provided. Permission Denied Use a virtual environment instead of sudo: python -m venv venv && source venv/bin/activate

Runtime Issues

Connection Problems

Symptoms: Cannot connect to Dex service Test connection:
Solutions:
  • Check network connectivity
  • Verify credentials (see Authentication Errors below)
  • Confirm Dex service is available

Authentication Errors

Symptoms: Invalid credentials, permission denied Verify credentials:
Solutions:
  • Set environment variables: SGP_ACCOUNT_ID and SGP_API_KEY
  • Verify your account has SGP access
  • Check API key hasn’t expired or been revoked

File Upload Errors

Symptoms: Upload fails, file too large, unsupported format Supported formats:
  • Images: PNG, JPEG, TIFF, HEIC, and more
  • PDFs: PDF
  • Spreadsheets: CSV, XLSX, XLS
  • Documents: PPTX, DOCX, TXT, RTF
Solutions:
  • Verify file path is correct
  • Check file size is under 100MB
  • Ensure file format is supported
  • Verify file isn’t corrupted

Parsing Errors

Symptoms: OCR fails, document can’t be processed Common causes:
  • Low quality scans (use at least 300 DPI)
  • Password-protected documents
  • Extremely complex layouts
  • Very large documents timing out
Solutions:
  1. Check document quality and resolution
  2. Remove password protection before uploading
  3. Try a different OCR engine:
  1. Split large documents into smaller chunks
  2. See complex layouts guide: Industry Document Types and Layout Challenges

Extraction Errors

Symptoms: Extraction fails, schema errors, timeout Common causes:
  • Invalid Pydantic schema
  • Model timeout or rate limiting
  • Insufficient context for extraction
  • Schema-data mismatch
Solutions:
  1. Validate your schema:
  1. Use clear prompts with detailed instructions
  2. Enable debugging:
  1. Use vector stores for large documents:

Performance Issues

Slow Parsing

Causes: Large documents, complex layouts, high OCR load Solutions:
  • Process documents asynchronously in batches
  • Cache parse results for frequently accessed documents

Slow Extraction

Causes: Large context, complex schema, model performance Solutions:
  • Use vector stores to reduce context size
  • Simplify extraction schema
  • Choose faster models for time-sensitive applications
  • Use batch processing
Causes: Large document collections, complex queries Solutions:
  • Use appropriate top_k values
  • Add filters to narrow search scope
  • Use vector_store.search_in_file() for file-specific searches
  • Create separate vector stores for different categories

Error Handling

Exception Types

Always wrap Dex operations in try-except blocks:

Common Exceptions


Debugging

Enable Logging

Inspect Parse Results

Validate Extraction Results

Test Components Individually


Getting Help

Support Channels

When Reporting Issues

Include:
  1. Error message - Full error text and stack trace
  2. Code snippet - Minimal reproducible example
  3. Document type - File format and characteristics
  4. SDK version - Output of pip show dex_sdk
  5. Environment - Python version, OS
  6. Expected vs actual behavior

Additional Resources