Troubleshooting

This guide covers common issues you might encounter when using Tinbox and how to resolve them.

Quick Diagnostics

Run the built-in diagnostic tool to check your setup:

tinbox doctor

This command checks:

System tools (poppler for PDF processing)
Python packages (pdf2image, python-docx, Pillow)
API key configuration (OpenAI, Anthropic, Google)
Local model availability (Ollama)

The doctor command is defined in src/tinbox/core/doctor.py and performs comprehensive environment validation.

Common Issues

PDF Translation Issues

Error: 'poppler-utils not found'

Problem: PDF processing requires poppler-utils to be installed.Solution: Install poppler for your operating system:

# macOS
brew install poppler

# Linux (Ubuntu/Debian)
sudo apt-get install poppler-utils

# Windows (Chocolatey)
choco install poppler

Verify installation:

tinbox doctor  # Should show poppler-utils as ✅
which pdfinfo  # Should show path to pdfinfo binary

From doctor.py:40-56:

def check_poppler() -> DoctorCheck:
    pdfinfo_path = shutil.which("pdfinfo")
    if pdfinfo_path:
        return DoctorCheck(
            name="poppler-utils",
            category="System Tools",
            ok=True,
            details=f"Found at {pdfinfo_path}",
        )
    return DoctorCheck(
        name="poppler-utils",
        category="System Tools",
        ok=False,
        hint="Install poppler: brew install poppler (macOS) or apt-get install poppler-utils (Linux)",
    )

Error: 'No module named pdf2image'

Problem: Missing Python package for PDF image conversion.Solution: Install PDF dependencies:

pip install tinbox[pdf]
# Or install all extras
pip install tinbox[all]

Verify installation:

tinbox doctor  # Should show pdf2image as ✅
python -c "import pdf2image; print(pdf2image.__version__)"

Error: 'Model does not support vision'

Problem: Trying to translate a PDF with a text-only model.Solution: Use a vision-capable model:

# ✅ Vision-capable models
tinbox translate --to es --model openai:gpt-4o document.pdf
tinbox translate --to es --model anthropic:claude-3-sonnet document.pdf
tinbox translate --to es --model gemini:gemini-2.5-pro document.pdf

# ❌ Text-only models (will fail)
tinbox translate --to es --model ollama:llama3.1:8b document.pdf  # No vision

Ollama models typically do not support vision. Convert PDFs to text first or use cloud models.

Poor PDF quality / High costs

Problem: PDF rendered at too high DPI, causing excessive token usage.Solution: Adjust DPI based on your needs:

# Default: 200 DPI (balanced)
tinbox translate --to es --pdf-dpi 200 --model openai:gpt-4o document.pdf

# Lower quality, lower cost: 150 DPI
tinbox translate --to es --pdf-dpi 150 --model openai:gpt-4o document.pdf

# High quality, higher cost: 300 DPI
tinbox translate --to es --pdf-dpi 300 --model openai:gpt-4o document.pdf

Use 150 DPI for simple text documents to save ~25% on costs.

API and Authentication Issues

Error: 'API key not found'

Problem: API key environment variable not set.Solution: Set the appropriate API key for your model provider:

# OpenAI
export OPENAI_API_KEY="sk-..."

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

# Google
export GOOGLE_API_KEY="AIza..."

Make it permanent (add to ~/.bashrc or ~/.zshrc):

echo 'export OPENAI_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc

Verify:

tinbox doctor  # Check API Keys section
echo $OPENAI_API_KEY  # Should show your key

From doctor.py:126-144:

def check_openai_key() -> DoctorCheck:
    key = os.environ.get("OPENAI_API_KEY")
    if key:
        masked = f"{key[:8]}...{key[-4:]}" if len(key) > 12 else "***"
        return DoctorCheck(
            name="OPENAI_API_KEY",
            category="API Keys",
            ok=True,
            details=f"Set ({masked})",
        )
    return DoctorCheck(
        name="OPENAI_API_KEY",
        category="API Keys",
        ok=False,
        hint="Set with: export OPENAI_API_KEY='your-key-here'",
    )

Error: 'Rate limit exceeded'

Problem: Hitting API rate limits from the model provider.Solutions:

Use checkpoints to resume:

tinbox translate --to es \
  --checkpoint-dir ./checkpoints \
  --model openai:gpt-4o \
  document.pdf
# If rate limited, wait and re-run - it will resume

Reduce checkpoint frequency to save less often:

tinbox translate --to es \
  --checkpoint-frequency 10 \
  --model openai:gpt-4o \
  document.pdf

Switch to local model (no rate limits):

ollama serve  # In another terminal
tinbox translate --to es --model ollama:llama3.1:8b document.txt

Rate limits vary by provider and API tier. Check your provider’s documentation.

Error: 'API timeout'

Problem: API request taking too long, especially with large pages or high reasoning effort.Solutions:

Use checkpoints to save progress:

tinbox translate --to es \
  --checkpoint-dir ./checkpoints \
  --model openai:gpt-4o \
  document.pdf

Reduce reasoning effort:

# Minimal is fastest
tinbox translate --to es --reasoning-effort minimal --model openai:gpt-4o doc.pdf

For PDFs, reduce DPI:

tinbox translate --to es --pdf-dpi 150 --model openai:gpt-4o document.pdf

For text, reduce context size:

tinbox translate --to es --context-size 1500 --model openai:gpt-4o document.txt

Package and Dependency Issues

Error: 'No module named docx'

Problem: Missing python-docx package for Word document support.Solution:

pip install tinbox[docx]
# Or install all extras
pip install tinbox[all]

Verify:

tinbox doctor  # Should show python-docx as ✅
python -c "import docx; print('OK')"

From doctor.py:81-100:

def check_python_docx() -> DoctorCheck:
    try:
        import docx
        return DoctorCheck(
            name="python-docx",
            category="Python Packages",
            ok=True,
            details="Installed",
        )
    except ImportError:
        return DoctorCheck(
            name="python-docx",
            category="Python Packages",
            ok=False,
            hint="Install with: pip install tinbox[docx]",
        )

Error: 'No module named PIL'

Problem: Missing Pillow package for image processing.Solution:

pip install pillow
# Or install all extras
pip install tinbox[all]

Verify:

tinbox doctor  # Should show Pillow as ✅
python -c "import PIL; print(PIL.__version__)"

Python version incompatibility

Problem: Tinbox requires Python 3.12 or higher.Check your version:

python --version  # Should be 3.12+

Solution: Install Python 3.12 or higher:

# macOS (using Homebrew)
brew install python@3.12

# Ubuntu/Debian
sudo apt install python3.12

# Or use pyenv
pyenv install 3.12.0
pyenv global 3.12.0

Translation Quality Issues

Inconsistent terminology across pages

Problem: Page-by-page algorithm doesn’t share context between pages.Solution: Enable glossary to maintain consistency:

# Auto-build glossary during translation
tinbox translate --to es \
  --glossary \
  --save-glossary terms.json \
  --model openai:gpt-4o \
  document.pdf

# Use existing glossary
tinbox translate --to es \
  --glossary-file terms.json \
  --model openai:gpt-4o \
  document.pdf

Glossary adds ~20% input token overhead but ensures consistent terminology (from cost.py:183-189).

Poor translation quality

Problem: Translation lacks nuance or makes errors.Solutions:

Increase reasoning effort:

tinbox translate --to es \
  --reasoning-effort high \
  --max-cost 20.00 \
  --model openai:gpt-4o \
  document.pdf

Use a higher-quality model:

# Claude Sonnet often produces higher quality
tinbox translate --to es --model anthropic:claude-3-sonnet document.pdf

For text files, use context-aware:

tinbox translate --to es \
  --algorithm context-aware \
  --context-size 2000 \
  --model openai:gpt-4o \
  document.txt

Provide a glossary with domain-specific terms:

{
  "entries": {
    "API": "Interfaz de Programación de Aplicaciones",
    "webhook": "webhook",
    "payload": "carga útil"
  }
}

Broken narrative flow in long documents

Problem: Using page-by-page for continuous text documents.Solution: Use context-aware algorithm for text files:

# Maintains context between chunks
tinbox translate --to fr \
  --algorithm context-aware \
  --context-size 2000 \
  --model openai:gpt-4o \
  novel.txt

Context-aware is not supported for PDFs. For PDF narratives, use glossary instead:

tinbox translate --to fr \
  --algorithm page \
  --glossary \
  --model openai:gpt-4o \
  novel.pdf

Cost and Performance Issues

Translation exceeds budget

Problem: Cost higher than expected.Solutions:

Set a cost limit:

tinbox translate --to es --max-cost 5.00 --model openai:gpt-4o document.pdf

Preview costs first:

tinbox translate --to es --dry-run --model openai:gpt-4o document.pdf

Use cheaper algorithm:

# Page-by-page has no context overhead
tinbox translate --to es --algorithm page --model openai:gpt-4o document.pdf

Use local models:

ollama serve
tinbox translate --to es --model ollama:llama3.1:8b document.txt  # Free

Reduce PDF DPI:

tinbox translate --to es --pdf-dpi 150 --model openai:gpt-4o document.pdf

See the Cost Optimization guide for more strategies.

Translation too slow

Problem: Translation taking longer than expected.Solutions:

Reduce reasoning effort:

tinbox translate --to es --reasoning-effort minimal --model openai:gpt-4o doc.pdf

For text, increase context size (fewer chunks to process):

tinbox translate --to es --context-size 3000 --model openai:gpt-4o document.txt

Use a faster model:

# GPT-4o is typically faster than Claude
tinbox translate --to es --model openai:gpt-4o document.pdf

For PDFs, reduce DPI:

tinbox translate --to es --pdf-dpi 150 --model openai:gpt-4o document.pdf

From cost.py:198-200, estimated speed:

Cloud models: ~30 tokens/second
Local models (Ollama): ~20 tokens/second

Warning: 'Large document detected'

Problem: Document has >50,000 tokens, costs may be high.From cost.py:206-210:

if estimated_total_tokens > 50000:
    warnings.append(
        f"Large document detected ({estimated_total_tokens:,} tokens). "
        "Consider using Ollama for no cost."
    )

Solutions:

Use local models (completely free):

ollama serve
tinbox translate --to es --model ollama:llama3.1:8b large_document.txt

Set a cost limit:

tinbox translate --to es --max-cost 10.00 --model openai:gpt-4o large_document.txt

Use checkpoints to process in segments:

tinbox translate --to es \
  --checkpoint-dir ./checkpoints \
  --checkpoint-frequency 10 \
  --max-cost 5.00 \
  --model openai:gpt-4o \
  large_document.pdf

# Resume after hitting limit
tinbox translate --to es \
  --checkpoint-dir ./checkpoints \
  --max-cost 5.00 \
  --model openai:gpt-4o \
  large_document.pdf

Ollama and Local Model Issues

Error: 'Ollama not found'

Problem: Ollama not installed or not in PATH.Solution: Install Ollama:

# Visit https://ollama.ai and download installer
# Or use Homebrew (macOS)
brew install ollama

Verify:

tinbox doctor  # Should show Ollama as ✅
which ollama   # Should show path
ollama --version

From doctor.py:187-203:

def check_ollama() -> DoctorCheck:
    ollama_path = shutil.which("ollama")
    if ollama_path:
        return DoctorCheck(
            name="Ollama",
            category="Local Models",
            ok=True,
            details=f"Found at {ollama_path}",
        )
    return DoctorCheck(
        name="Ollama",
        category="Local Models",
        ok=False,
        hint="Install from: https://ollama.ai (optional, for local models)",
    )

Error: 'Connection refused' when using Ollama

Problem: Ollama server not running.Solution: Start Ollama server:

# In a separate terminal
ollama serve

Then translate:

tinbox translate --to es --model ollama:llama3.1:8b document.txt

Keep ollama serve running in the background for all local model operations.

Error: 'Model not found' with Ollama

Problem: Model not downloaded.Solution: Pull the model first:

ollama pull llama3.1:8b
ollama list  # Verify model is downloaded

Then translate:

tinbox translate --to es --model ollama:llama3.1:8b document.txt

Checkpoint and Resume Issues

Translation not resuming from checkpoint

Problem: Re-running translation starts from beginning.Causes and solutions:

Different checkpoint directory:

# Make sure to use the SAME checkpoint directory
tinbox translate --to es --checkpoint-dir ./checkpoints --model openai:gpt-4o doc.pdf
# Resume
tinbox translate --to es --checkpoint-dir ./checkpoints --model openai:gpt-4o doc.pdf

Different source or target language:

# These are different jobs, won't resume
tinbox translate --to es --checkpoint-dir ./chk --model openai:gpt-4o doc.pdf  # es
tinbox translate --to fr --checkpoint-dir ./chk --model openai:gpt-4o doc.pdf  # fr - different!

Different algorithm:

# These are different jobs
tinbox translate --to es --algorithm page --checkpoint-dir ./chk --model openai:gpt-4o doc.pdf
tinbox translate --to es --algorithm context-aware --checkpoint-dir ./chk --model openai:gpt-4o doc.pdf  # Won't resume

How to force restart (ignore checkpoints)

Problem: Want to start fresh, ignoring existing checkpoints.Solution: Delete the checkpoint directory:

rm -rf ./checkpoints
tinbox translate --to es --checkpoint-dir ./checkpoints --model openai:gpt-4o doc.pdf

Or use a different checkpoint directory:

tinbox translate --to es --checkpoint-dir ./checkpoints-new --model openai:gpt-4o doc.pdf

Getting Help

Run tinbox doctor

tinbox doctor

Check for environment and dependency issues.

Check the README

Review troubleshooting section in the README.

Enable verbose logging

# Set log level to DEBUG for detailed output
export TINBOX_LOG_LEVEL=DEBUG
tinbox translate --to es --model openai:gpt-4o document.pdf

Report issues

If you’ve found a bug, report it on GitHub:

Include tinbox doctor output
Include error messages and logs
Provide sample command that reproduces the issue
Mention Python version and OS

Doctor Command Reference

The tinbox doctor command performs these checks:

System Tools

Check	Category	Required For
poppler-utils	System Tools	PDF processing

Python Packages

Package	Category	Required For
pdf2image	Python Packages	PDF to image conversion
python-docx	Python Packages	Word document support
Pillow	Python Packages	Image processing

API Keys (Optional)

Key	Category	Required For
OPENAI_API_KEY	API Keys	OpenAI models (GPT-4o, GPT-5, etc.)
ANTHROPIC_API_KEY	API Keys	Anthropic models (Claude)
GOOGLE_API_KEY	API Keys	Google models (Gemini)

Local Models (Optional)

Tool	Category	Required For
Ollama	Local Models	Free local model inference

From doctor.py:206-227, the doctor command runs all checks and reports:

✅ for passing checks
❌ for failing checks
Helpful hints for fixing issues

Cost Optimization

Strategies to reduce costs and prevent budget overruns

Algorithm Comparison

Choose the right algorithm for your use case

​Quick Diagnostics

​Common Issues

​PDF Translation Issues

​API and Authentication Issues

​Package and Dependency Issues

​Translation Quality Issues

​Cost and Performance Issues

​Ollama and Local Model Issues

​Checkpoint and Resume Issues

​Getting Help

​Doctor Command Reference

​System Tools

​Python Packages

​API Keys (Optional)

​Local Models (Optional)

​Related Topics

Cost Optimization

Algorithm Comparison

Quick Diagnostics

Common Issues

PDF Translation Issues

API and Authentication Issues

Package and Dependency Issues

Translation Quality Issues

Cost and Performance Issues

Ollama and Local Model Issues

Checkpoint and Resume Issues

Getting Help

Doctor Command Reference

System Tools

Python Packages

API Keys (Optional)

Local Models (Optional)

Related Topics