Skip to main content

Compatibility Issues and Solutions

Overview​

This document covers compatibility issues that have been identified and resolved in the LLM Platform, along with troubleshooting steps for common problems.

Field Encrypt Compatibility​

Issue Description​

The LLM Platform experienced compatibility issues with the Field Encrypt module, specifically around encrypted field storage and configuration.

Symptoms​

  • Field encryption not working properly
  • Configuration import/export failures
  • Data loss in encrypted fields
  • Module dependency conflicts

Root Cause​

  • Incompatible field storage definitions
  • Conflicting encryption key management
  • Improper field formatter configuration

Solution​

✅ RESOLVED - The following changes have been implemented:

Field Storage Updates​

  • Updated field storage definitions to be compatible with Field Encrypt
  • Proper encryption key references in field configuration
  • Corrected field formatter and widget configurations

Configuration Changes​

# Updated field storage for encrypted fields
field.storage.node.field_api_key:
  type: string_encrypted
  settings:
    encryption_profile: ai_api_keys
    max_length: 255

Key Management​

  • Proper encryption profile configuration
  • Secure key storage implementation
  • Backup and recovery procedures for encrypted data

Prevention​

  • Test encryption functionality after module updates
  • Validate field configurations before deployment
  • Regular backup of encryption keys and profiles

Module Dependency Issues​

Issue Description​

Circular dependencies and conflicting module requirements causing installation failures and update problems.

Symptoms​

  • Module installation failures
  • Circular dependency errors
  • Configuration import conflicts
  • Service container build failures

Root Cause Analysis​

  • Improper module dependency declarations
  • Cross-module service dependencies
  • Configuration conflicts between modules

Resolution Status​

✅ RESOLVED - Comprehensive dependency refactoring completed:

Dependency Hierarchy​

Core Drupal Modules
├── AI Module (base)
├── LLM Module
│   ├── Depends on: AI Module
│   └── Provides: Core AI functionality
├── MCP Registry
│   ├── Depends on: LLM Module
│   └── Provides: Protocol management
└── Alternative Services
    ├── Depends on: System
    └── Provides: Service discovery

Service Container Fixes​

  • Removed circular service dependencies
  • Proper service injection patterns
  • Lazy loading for optional services

Configuration Separation​

  • Core configuration in module install files
  • Site-specific configuration in recipes
  • Clear separation of concerns

Prevention Steps​

  • Regular dependency analysis
  • Automated testing of module installation
  • Configuration validation in CI/CD pipeline

Service Configuration Issues​

Issue Description​

Service container configuration conflicts causing runtime errors and performance issues.

Symptoms​

  • Service not found errors
  • Incorrect service injection
  • Performance degradation
  • Memory leaks in service containers

Identified Problems​

  1. Circular Service Dependencies: Services depending on each other
  2. Incorrect Service Definitions: Improper service.yml configurations
  3. Missing Service Tags: Required service tags not properly declared
  4. Scope Issues: Services with incorrect scope definitions

Resolution Summary​

✅ COMPLETE - All service configuration issues have been resolved:

Service Definition Updates​

# Example corrected service definition
services:
  llm.ai_provider_manager:
    class: Drupal\llm\Service\AiProviderManager
    arguments: ['@config.factory', '@logger.factory']
    tags:
      - { name: ai_provider_manager }

Dependency Injection Fixes​

  • Proper constructor injection
  • Interface-based dependencies
  • Lazy service loading where appropriate

Service Discovery​

  • Automatic service discovery for plugins
  • Proper service tagging
  • Dynamic service registration

Testing Protocol​

  • Unit tests for all services
  • Integration tests for service interactions
  • Performance testing for service containers

README Compatibility Updates​

Migration to Modern Standards​

The platform documentation has been updated to follow modern Drupal and documentation standards:

Documentation Structure​

  • Consistent README format across all modules
  • Proper Markdown formatting
  • Clear installation and usage instructions
  • Comprehensive troubleshooting sections

Content Updates​

  • Updated for Drupal 10.3+ compatibility
  • Recipe API v1 compliance
  • Modern development practices
  • Security best practices
  • Proper internal documentation linking
  • External resource references
  • API documentation integration

Common Configuration Issues​

Cache Configuration Problems​

Symptoms​

  • Slow page loads
  • Configuration not updating
  • Cache tag invalidation issues

Solutions​

# Clear all caches
drush cr

# Rebuild cache tags
drush cache:rebuild

# Check cache configuration
drush config:get system.performance

Database Configuration Issues​

Symptoms​

  • Connection timeouts
  • Query performance issues
  • Migration failures

Solutions​

# Check database status
drush status

# Run database updates
drush updatedb

# Check for database schema issues
drush entity:updates

Search API Configuration​

Symptoms​

  • Search not working
  • Index not updating
  • Facet configuration errors

Solutions​

# Rebuild search indexes
drush search-api:rebuild-tracker

# Check search server status
drush search-api:server-list

# Clear search caches
drush search-api:clear

Performance Issues​

Memory Usage Problems​

Symptoms​

  • PHP memory limit exceeded
  • Slow response times
  • Service container bloat

Solutions​

# Increase PHP memory limit
memory_limit = 1024M

# Enable opcache
opcache.enable = 1
opcache.memory_consumption = 256

Database Performance​

Symptoms​

  • Slow queries
  • High database load
  • Connection pool exhaustion

Solutions​

-- Enable query cache
SET GLOBAL query_cache_type = ON;
SET GLOBAL query_cache_size = 256M;

-- Optimize tables
OPTIMIZE TABLE node;
OPTIMIZE TABLE cache_bootstrap;

Security Configuration Issues​

SSL/TLS Configuration​

Symptoms​

  • Mixed content warnings
  • SSL certificate errors
  • Insecure connections

Solutions​

# Apache SSL configuration
SSLEngine on
SSLCertificateFile /path/to/certificate.crt
SSLCertificateKeyFile /path/to/private.key
SSLProtocol TLSv1.2 TLSv1.3

API Security​

Symptoms​

  • Unauthorized API access
  • Rate limiting not working
  • Authentication failures

Solutions​

# Update API security configuration
api_normalizer.settings:
  rate_limiting:
    enabled: true
    requests_per_minute: 60
  authentication:
    required: true
    methods: ['jwt', 'oauth2']

Debugging Tools and Commands​

Diagnostic Commands​

# Check system status
drush status

# View recent log entries
drush watchdog:show

# Check configuration status
drush config:status

# Validate configuration
drush config:validate

# Check for security updates
drush security:check

Performance Profiling​

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

# Check query performance
drush sql:query "SHOW FULL PROCESSLIST;"

# Analyze slow queries
drush sql:query "SELECT * FROM mysql.slow_log LIMIT 10;"

Cache Debugging​

# Check cache status
drush cache:get system.site

# Monitor cache performance
drush cache:rebuild --verbose

# Check cache tags
drush cache:tags

Prevention Strategies​

Development Best Practices​

  1. Regular Testing: Implement comprehensive testing suite
  2. Code Review: Mandatory code review for all changes
  3. Documentation: Keep documentation up to date
  4. Version Control: Proper branching and tagging strategy

Monitoring and Alerting​

  1. Health Checks: Regular health monitoring
  2. Performance Monitoring: Application performance monitoring
  3. Log Analysis: Automated log analysis and alerting
  4. Security Scanning: Regular security vulnerability scanning

Update Management​

  1. Staged Updates: Test updates in staging environment
  2. Rollback Plans: Always have rollback procedures
  3. Compatibility Testing: Test compatibility with all dependencies
  4. Documentation Updates: Update documentation with changes

Support Resources​

  • Issue Tracking: GitHub Issues for bug reports
  • Community Support: Drupal community forums
  • Professional Support: Enterprise support contracts available
  • Documentation: Comprehensive documentation in /docs

This compatibility guide is regularly updated as new issues are identified and resolved. Always check the latest version for current compatibility status and solutions.