Skip to content

Troubleshooting

This guide helps you diagnose and resolve common issues with TMGMT Lara Translate and Symfony Messenger processing.

Quick Diagnosis Checklist

1. Basic Health Check

# Verify all required modules are enabled
drush pm:status | grep -E "(tmgmt|sm|key)"

# Check module versions
drush pm:list --status=enabled --format=table | grep -E "(tmgmt|sm|key)"

2. Configuration Verification

# Check Lara translator configuration
drush config:get tmgmt.translator.lara_translate

# Verify messenger settings
drush config:get messenger.settings

# Check key storage for API credentials
drush key:list | grep -i lara

3. Recent Error Check

# Show recent translation errors
drush watchdog:show --severity=error --type=tmgmt_laratranslate --limit=10

# Show messenger-related errors
drush watchdog:show --severity=error --type=messenger --limit=5

Common Issues and Solutions

Issue: Jobs Not Processing

Symptoms: Jobs stay in "Submitted" state, no progress

Possible Causes: - Symfony Messenger not properly configured - Message handler not registered - Transport configuration issues

Solutions:

Check Messenger Setup

# Verify messenger module is enabled
drush pm:status | grep messenger

# Check message handlers
drush messenger:list-handlers | grep TranslationJobMessageHandler

# Test message processing
drush messenger:consume async --limit=1 --verbose

Verify Handler Registration

# Clear caches to ensure handlers are registered
drush cache:rebuild

# Check service definition
drush config:debug | grep TranslationJobMessageHandler

Manual Message Processing

# Process pending messages manually
drush messenger:consume async --limit=10

# Process with verbose output for debugging
drush messenger:consume async --limit=1 --verbose

Issue: Authentication Failures

Symptoms: "Authentication failed" or "Invalid credentials" errors

Possible Causes: - Incorrect API credentials - Key module configuration issues - Expired API access

Solutions:

Verify API Credentials

# Check stored keys
drush key:list | grep -i lara

# Test key values (be careful with sensitive data)
drush key:get lara_access_key_id
drush key:get lara_access_key_secret

Reconfigure Keys

  1. Go to Configuration → System → Keys (/admin/config/system/keys)
  2. Edit your Lara API keys
  3. Verify the key values are correct
  4. Test with a small translation job

Check API Access

# Test API connectivity (replace with your actual test)
curl -H "Authorization: Bearer YOUR_KEY" https://api.laratranslate.com/v1/languages

Issue: Language Mapping Errors

Symptoms: "Unsupported language" or "Language mapping not found"

Possible Causes: - Target language not supported by Lara - Incorrect language code mapping - Missing custom mappings

Solutions:

Check Supported Languages

# Test Lara API for supported languages
drush tmgmt:languages --translator=lara_translate

Verify Language Mappings

  1. Go to Configuration → Translation Management → Providers
  2. Edit your Lara translator
  3. Check Language mappings section
  4. Add custom mappings if needed

Debug Language Codes

<?php
// Debug script to check language mappings
$translator = \Drupal::entityTypeManager()->getStorage('tmgmt_translator')->load('lara_translate');
$plugin = $translator->getPlugin();
$supported = $plugin->getSupportedRemoteLanguages($translator);
print_r($supported);
?>

Issue: Quota Exceeded

Symptoms: "Quota exceeded" errors, jobs retrying repeatedly

Possible Causes: - Lara API quota exhausted - High volume of translation requests - Concurrent processing limits

Solutions:

Monitor Quota Usage

# Check for quota errors in logs
drush watchdog:show --type=tmgmt_laratranslate | grep -i quota

# Count recent quota errors
drush watchdog:show --type=tmgmt_laratranslate | grep -i quota | wc -l

Implement Rate Limiting

  1. Reduce concurrent job submissions
  2. Implement job scheduling for off-peak hours
  3. Monitor usage patterns and adjust accordingly

Wait and Retry

  • Quota errors are transient and will auto-retry
  • Monitor job status for automatic recovery
  • Contact Lara support if quota issues persist

Issue: Network Connectivity

Symptoms: "Connection timeout", "Network error", "Unable to reach API"

Possible Causes: - Firewall blocking API access - DNS resolution issues - SSL/TLS certificate problems

Solutions:

Test Network Connectivity

# Test basic connectivity
ping api.laratranslate.com

# Test HTTPS access
curl -I https://api.laratranslate.com

# Test with verbose output
curl -v https://api.laratranslate.com/v1/languages

Check Firewall Rules

Ensure your server can access: - api.laratranslate.com on port 443 (HTTPS) - Any required proxy configurations

Verify SSL Certificates

# Check SSL certificate
openssl s_client -connect api.laratranslate.com:443 -servername api.laratranslate.com

# Test certificate chain
curl --cacert /etc/ssl/certs/ca-certificates.crt https://api.laratranslate.com

Issue: Large Content Processing

Symptoms: Jobs with large content fail or timeout

Possible Causes: - Content exceeds API limits - Memory issues during processing - Text chunking problems

Solutions:

Check Content Size

# Check job item sizes
drush tmgmt-job:list --format=yaml | grep -A 5 -B 5 "word_count"

# Monitor memory usage during processing
drush status --format=json | jq '.["php-memory"]'

Verify Text Chunking

The module automatically chunks large content, but you can verify:

<?php
// Debug text chunking
$chunker = \Drupal::service('tmgmt_laratranslate.text_chunker');
$large_text = str_repeat('Test content. ', 2000);
$chunks = $chunker->splitText($large_text);
echo "Chunks created: " . count($chunks);
?>

Optimize Content

  • Break very large content into smaller pieces before translation
  • Remove unnecessary HTML tags
  • Consider splitting complex pages

Advanced Troubleshooting

Debug Mode Configuration

Enable detailed logging for troubleshooting:

# Enable debug logging
drush config:set system.logging error_level verbose

# Clear caches to apply
drush cache:rebuild

Custom Debug Scripts

Job Status Script

#!/bin/bash
echo "=== TMGMT Lara Translate Debug ==="
echo "Active Jobs:"
drush tmgmt-job:list --status=active --format=table
echo ""
echo "Recent Errors:"
drush watchdog:show --severity=error --type=tmgmt_laratranslate --limit=5
echo ""
echo "Messenger Status:"
drush messenger:info

API Test Script

<?php
// Test Lara API connectivity
$translator = \Drupal::entityTypeManager()->getStorage('tmgmt_translator')->load('lara_translate');
$plugin = $translator->getPlugin();

try {
    $lara_translator = $plugin->createLaraTranslator($translator);
    $languages = $lara_translator->getLanguages();
    echo "API Test: SUCCESS\n";
    echo "Supported languages: " . count($languages) . "\n";
} catch (Exception $e) {
    echo "API Test: FAILED\n";
    echo "Error: " . $e->getMessage() . "\n";
}
?>

Performance Issues

Identify Bottlenecks

# Check system resources
drush status --format=json | jq '.["php-version", "php-memory", "db-status"]'

# Monitor message queue depth
drush messenger:stats

# Check for stuck messages
drush messenger:info

Optimize Processing

  1. Increase worker processes: Configure more messenger consumers
  2. Adjust retry limits: Fine-tune retry behavior
  3. Monitor memory usage: Ensure adequate PHP memory limits

When to Escalate

Gather This Information

Before seeking help, collect:

  1. Error logs: Recent tmgmt_laratranslate and messenger logs
  2. Configuration: Export of translator and messenger settings
  3. System info: Drupal version, PHP version, module versions
  4. Job details: Specific job IDs that are failing
  5. Network test results: API connectivity test results

Support Channels

  • Drupal.org issue queue: Project-specific issues
  • Lara support: API and service-related problems
  • Community forums: General usage questions

Prevention and Maintenance

Regular Maintenance Tasks

# Clear message queues (if needed)
drush messenger:clear async

# Clean up old logs
drush watchdog:clear --type=tmgmt_laratranslate --older-than=30d

# Verify configuration integrity
drush config:export --directory=/tmp/backup

Monitoring Setup

  • Set up log monitoring for error patterns
  • Configure alerts for high failure rates
  • Regular health checks on API connectivity

Best Practices

  • Test with small jobs before large submissions
  • Monitor quota usage regularly
  • Keep API credentials secure and updated
  • Review error logs periodically