Troubleshooting¶

Common issues and their solutions.

Translation Errors¶

"The pair is not available"¶

The requested language pair isn't supported by the interpreter.

# Check if models download successfully
es-translator \
  --url "http://localhost:9200" \
  --index test \
  --source-language fr \
  --target-language en \
  --stdout-loglevel DEBUG \
  --dry-run

# List available pairs
es-translator-pairs

# Use intermediary language
es-translator \
  --interpreter apertium \
  --source-language pt \
  --target-language en \
  --intermediary-language es \
  ...

"Apertium is not installed"¶

Apertium requires system packages. Install them:

wget https://apertium.projectjj.com/apt/install-nightly.sh -O - | sudo bash
sudo apt install apertium-all-dev

Or use Argos instead (default, no installation required):

es-translator --interpreter argos ...

Invalid Language Code¶

Use standard ISO 639-1 (2-letter) or ISO 639-3 (3-letter) codes:

Elasticsearch Issues¶

Connection Refused¶

Can't connect to Elasticsearch.

Check Elasticsearch is running:

curl http://localhost:9200

Docker networking issues:

# Use host network
docker run --network host icij/es-translator ...

# Or use host.docker.internal (Docker Desktop)
docker run icij/es-translator es-translator \
  --url "http://host.docker.internal:9200" ...

Scroll Context Lost¶

For large datasets, the scroll context may expire.

Increase scroll duration:

es-translator --scan-scroll 30m ...

Use planned mode for very large datasets:

# Queue documents (no scroll needed during execution)
es-translator --plan --broker-url redis://... ...

# Process from queue
es-translator-tasks --broker-url redis://...

Index Not Found¶

Verify the index exists:

curl http://localhost:9200/_cat/indices

Performance Issues¶

Translation Too Slow¶

Increase parallel workers:

es-translator --pool-size 4 ...

Use Apertium (faster but lower quality):

es-translator --interpreter apertium ...

Filter to translate only what's needed:

es-translator --query-string "type:Document AND status:published" ...

Memory Issues¶

Large documents or too many workers can exhaust memory.

Limit content length:

es-translator --max-content-length 10M ...

Reduce worker count:

es-translator --pool-size 1 ...

Use Apertium (lower memory usage):

es-translator --interpreter apertium ...

High Elasticsearch Load¶

Add throttling:

es-translator --throttle 100 ...  # 100ms delay

Reduce pool size:

es-translator --pool-size 1 ...

Distributed Mode Issues¶

Workers Not Processing¶

Check Redis connectivity:

redis-cli -h redis ping

Verify broker URL matches:

# Planning
es-translator --broker-url "redis://redis:6379" --plan ...

# Workers (must use same URL)
es-translator-tasks --broker-url "redis://redis:6379"

Check worker logs:

es-translator-tasks --broker-url "redis://..." --stdout-loglevel DEBUG

Tasks Stuck in Queue¶

Check Celery status:

# If using Docker
docker logs es-translator-worker

Restart workers:

docker restart es-translator-worker

Docker Issues¶

Container Exits Immediately¶

Check logs:

docker logs <container-id>

Common causes:

• Missing required arguments (--source-language, --target-language)
• Invalid Elasticsearch URL
• Network connectivity issues

Permission Denied¶

For data directory access:

docker run -v /path/to/data:/data:rw icij/es-translator \
  es-translator --data-dir /data ...

Debug Mode¶

Enable detailed logging to diagnose issues:

es-translator \
  --stdout-loglevel DEBUG \
  --dry-run \
  ...

Dry Run¶

Test configuration without modifying data:

es-translator --dry-run ...

Getting Help¶

If you're still stuck:

1. Check GitHub Issues
2. Open a new issue with:
   • es-translator version
   • Command you ran
   • Full error message
   • Elasticsearch version