Troubleshooting Dex

​

Installation Issues

​

Installing the Dex SDK

• AWS CLI installed and configured
• Access to Scale’s production AWS account

1. Authenticate with AWS SSO:

aws sso login

2. Configure pip for CodeArtifact:

aws codeartifact login \
    --tool pip \
    --domain scale \
    --repository scale-pypi \
    --profile production-developer \
    --region us-west-2

3. Install the SDK: The exact command can be found on GitHub, in the introduction notebooks.
4. Verify installation:

import dex_sdk
print(f"Dex SDK version: {dex_sdk.__version__}")

​

Common Installation Errors

​

Runtime Issues

​

Connection Problems

import requests
response = requests.get("https://dex.sgp.scale.com/health")
print(f"Status: {response.status_code}")

• Check network connectivity
• Verify credentials (see Authentication Errors below)
• Confirm Dex service is available

​

Authentication Errors

import os
sgp_account_id = os.getenv("SGP_ACCOUNT_ID")
sgp_api_key = os.getenv("SGP_API_KEY")

if not sgp_account_id or not sgp_api_key:
    print("❌ Missing credentials")

• 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

• Images: PNG, JPEG, TIFF, HEIC, and more
• PDFs: PDF
• Spreadsheets: CSV, XLSX, XLS
• Documents: PPTX, DOCX, TXT, RTF

• Verify file path is correct
• Check file size is under 100MB
• Ensure file format is supported
• Verify file isn’t corrupted

​

Parsing Errors

• Low quality scans (use at least 300 DPI)
• Password-protected documents
• Extremely complex layouts
• Very large documents timing out

1. Check document quality and resolution
2. Remove password protection before uploading
3. Try a different OCR engine:

from dex_sdk.types import ParseEngine, ReductoParseJobParams

parse_result = await dex_file.parse(
    ReductoParseJobParams(engine=ParseEngine.SCALE_OCR)
)

4. Split large documents into smaller chunks
5. See complex layouts guide: Industry Document Types and Layout Challenges

​

Extraction Errors

• Invalid Pydantic schema
• Model timeout or rate limiting
• Insufficient context for extraction
• Schema-data mismatch

1. Validate your schema:

from pydantic import BaseModel, Field

class MySchema(BaseModel):
    field_name: str = Field(description="Clear description")

schema = MySchema.model_json_schema()

2. Use clear prompts with detailed instructions
3. Enable debugging:

extract_result = await parse_result.extract(
    extraction_schema=schema,
    user_prompt="Your detailed prompt",
    model="openai/gpt-4o",
    generate_citations=True,
    generate_confidence=True,
)

4. Use vector stores for large documents:

vector_store = await project.create_vector_store(
    name="My Store",
    engine=VectorStoreEngines.SGP_KNOWLEDGE_BASE,
    embedding_model="openai/text-embedding-3-large",
)
await vector_store.add_parse_results([parse_result.id])

extract_result = await vector_store.extract(
    extraction_schema=schema,
    user_prompt=user_prompt,
    model="openai/gpt-4o",
)

​

Performance Issues

​

Slow Parsing

• Process documents asynchronously in batches
• Cache parse results for frequently accessed documents

​

Slow Extraction

• Use vector stores to reduce context size
• Simplify extraction schema
• Choose faster models for time-sensitive applications
• Use batch processing

​

Slow Vector Store Search

• 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

from dex_sdk.exceptions import DexException

try:
    project = await dex_client.create_project(...)
    dex_file = await project.upload_file(...)
    parse_result = await dex_file.parse(...)
    extract_result = await parse_result.extract(...)
except DexException as e:
    print(f"Dex error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

​

Common Exceptions

​

Debugging

​

Enable Logging

import logging

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger("dex_sdk")
logger.setLevel(logging.DEBUG)

​

Inspect Parse Results

parse_data = parse_result.data.model_dump()
print(f"Pages: {len(parse_data.get('pages', []))}")
print(f"Chunks: {len(parse_data.get('chunks', []))}")

​

Validate Extraction Results

extraction_data = extract_result.data.model_dump()

if 'citations' in extraction_data:
    print(f"Citations found: {len(extraction_data['citations'])}")

if 'confidence' in extraction_data:
    print(f"Confidence: {extraction_data['confidence']}")

​

Test Components Individually

try:
    project = await dex_client.create_project(...)
    print("✅ Project created")

    dex_file = await project.upload_file(...)
    print("✅ File uploaded")

    parse_result = await dex_file.parse(...)
    print("✅ Parsing completed")

    extract_result = await parse_result.extract(...)
    print("✅ Extraction completed")
except Exception as e:
    print(f"❌ Failed at step: {e}")

​

Getting Help

​

Support Channels

• Slack: #dex-help for Dex team support
• Documentation: Dex Documentation

​

When Reporting Issues

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

• Getting Started Guide - Quick start tutorial
• File Management - Upload and pagination
• Parse - Parse engines and async jobs
• Vector Stores - Semantic search and RAG
• Extract - Data extraction and batch processing
• Best Practices - Common patterns and optimization
• API Reference - Complete SDK documentation
• Introduction to Dex - Core concepts