Troubleshooting

• 1: Common Errors
• 2: Performance Issues
• 3: Layout Builder Issues
• 4: Upgrade Problems
• 5: Activity Finder Issues
• 6: Debugging Techniques

1 - Common Errors

This guide covers the most common errors you’ll encounter and how to fix them. Use Ctrl+F / Cmd+F to search for your specific error message.

White Screen of Death (WSOD)

Symptoms: Blank white page with no content or error messages.

Causes & Solutions:

1. PHP Fatal Error

   # Check PHP error logs
   tail -f /var/log/apache2/error.log
   # Or
   drush watchdog:tail
   

2. Memory Limit Exceeded

   # In settings.php or settings.local.php
   ini_set('memory_limit', '512M');
   

3. Module Conflict

   # Disable recently installed modules
   drush pmu module_name -y
   drush cr
   

4. Corrupted Cache

   # Clear all caches
   drush cr
   # Or via database if Drush fails
   drush sql-cli
   TRUNCATE TABLE cache_bootstrap;
   TRUNCATE TABLE cache_render;
   exit
   

Prevention:

• Enable error reporting in development: $config['system.logging']['error_level'] = 'verbose';
• Always test module updates on staging first

Permission Denied Errors

Error: Warning: file_put_contents(sites/default/files/...): failed to open stream: Permission denied

Solutions:

1. Fix File Permissions

   # Set correct ownership (replace www-data with your web server user)
   sudo chown -R www-data:www-data sites/default/files
   
   # Set correct permissions
   sudo chmod -R 755 sites/default/files
   

2. SELinux Issues (CentOS/RHEL)

   # Check SELinux status
   getenforce
   
   # Set correct SELinux context
   sudo chcon -R -t httpd_sys_rw_content_t sites/default/files
   

3. Temporary Fix (Development Only)

   chmod 777 sites/default/files
   # NEVER use 777 in production!
   

Composer Dependency Conflicts

Error: Your requirements could not be resolved to an installable set of packages.

Solutions:

1. Update Composer

   composer self-update
   composer --version  # Should be 2.0+
   

2. Clear Composer Cache

   composer clear-cache
   composer update --no-cache
   

3. Check PHP Version

   php -v  # Should match composer.json requirements
   

4. Use Specific Versions

   # Instead of ymca/website-services:*
   composer require ymca/website-services:^11.1
   

5. Diagnose Conflicts

   composer why-not ymca/website-services 11.1.0
   composer prohibits ymca/website-services 11.1.0
   

Database Update Failures

Error: Exception: ... in update hook

Solutions:

1. Backup First!

   drush sql-dump > backup-$(date +%Y%m%d).sql
   

2. Run in Safe Mode

   # Skip problematic hooks
   drush updb --entity-updates -y
   

3. Check Error Logs

   drush watchdog:show --severity=Error
   

4. Manual Fix

   # Mark update as complete manually (last resort)
   drush sql-cli
   INSERT INTO key_value (collection, name, value)
   VALUES ('system.schema', 'module_name', 's:4:"9001";');
   exit
   

Need more help? See Debugging Techniques or Get Support.

2 - Performance Issues

Having performance problems? This guide will help you diagnose and optimize your YMCA website.

Slow Page Loads

Symptoms: Pages take 5+ seconds to load.

Diagnosis:

1. Check Caching

   • Admin: /admin/config/development/performance
   • Ensure “Aggregate CSS files” is checked
   • Ensure “Aggregate JavaScript files” is checked
   • Enable page caching for anonymous users

2. Install Devel Module (Development only)

   composer require drupal/devel --dev
   drush en devel webprofiler -y
   

   • Visit any page to see performance metrics
   • Check for slow queries

3. Database Performance

   # Check slow queries
   drush sql-query "SHOW FULL PROCESSLIST;"
   
   # Check database size
   drush sql-query "SELECT
     table_name AS 'Table',
     ROUND(((data_length + index_length) / 1024 / 1024), 2) AS 'Size (MB)'
   FROM information_schema.TABLES
   WHERE table_schema = 'DATABASE_NAME'
   ORDER BY (data_length + index_length) DESC;"
   

Solutions:

1. Enable Redis/Memcache

   composer require drupal/redis
   drush en redis -y
   

   // In settings.php
   $settings['redis.connection']['interface'] = 'PhpRedis';
   $settings['redis.connection']['host'] = '127.0.0.1';
   $settings['cache']['default'] = 'cache.backend.redis';
   

2. Optimize Images

   • Use WebP format where possible
   • Enable image optimization: /admin/config/media/image-styles

3. Clean Up Database

   # Truncate watchdog logs
   drush sql-query "TRUNCATE watchdog;"
   
   # Remove old revisions
   drush entity:delete node --bundle=article --chunks=10
   

High Memory Usage

Error: PHP Fatal error: Allowed memory size of ... bytes exhausted

Solutions:

1. Increase PHP Memory Limit

   // In settings.php
   ini_set('memory_limit', '512M');
   

2. For Composer

   php -d memory_limit=-1 /usr/local/bin/composer update
   

3. Optimize Composer Autoloader

   composer dump-autoload --optimize
   

Need more help? See Debugging Techniques or Get Support.

3 - Layout Builder Issues

Having trouble with Layout Builder? Find solutions to common issues below.

Blocks Not Appearing

Problem: Added blocks don’t show up on the page.

Solutions:

1. Check Block Placement

   • Ensure block is in a visible region
   • Check block’s visibility settings

2. Clear Cache

   drush cr
   

3. Check Permissions

   • Visit /admin/people/permissions
   • Ensure role has “Create and edit custom blocks”

4. Check Block Configuration

   • Inline blocks must be configured before adding
   • Some blocks require additional fields

Section Styling Not Working

Problem: Section background colors or styles don’t apply.

Solutions:

1. Clear Cache

   drush cr
   

2. Check Theme Compatibility

   • Small Y template required for some styles
   • Some styles only work with specific themes

3. Rebuild CSS

   drush cron
   drush cr
   

Media Upload Failures

Error: The file could not be uploaded.

Solutions:

1. Check File Permissions

   chmod -R 755 sites/default/files
   chown -R www-data:www-data sites/default/files
   

2. Check File Size Limits

   // In php.ini or .htaccess
   upload_max_filesize = 64M
   post_max_size = 64M
   

3. Check Disk Space

   df -h
   

4. Check Allowed File Extensions

   • Visit /admin/config/media/file-system
   • Add extension if needed (e.g., .webp)

Need more help? Browse the Block Library or Get Support.

4 - Upgrade Problems

Encountering problems during an upgrade? Find solutions to common upgrade issues below.

Version Compatibility Issues

Error: ymca/website-services requires drupal/core ^11.0 but drupal/core 10.x.x is installed

Solutions:

1. Check Current Versions

   drush status
   composer show | grep drupal/core
   

2. Follow Official Upgrade Path

   • Drupal 9 → 10: Upgrade Guide
   • Drupal 10 → 11: Migration Guide (Beta - stable Q4 2025)

3. Use Upgrade Status Module

   composer require drupal/upgrade_status --dev
   drush en upgrade_status -y
   

   • Visit /admin/reports/upgrade-status

Module Conflicts After Upgrade

Problem: Site broken after upgrading modules.

Solutions:

1. Restore from Backup

   drush sql-drop
   drush sql-cli < backup-20250101.sql
   

2. Update One Module at a Time

   composer update drupal/module_name
   drush updb -y
   drush cr
   # Test thoroughly before updating next module
   

3. Check Incompatible Modules

   drush pm:list --status=enabled
   # Check drupal.org for Drupal 11 compatibility
   

Configuration Import Failures

Error: Entities exist of type ... These entities need to be deleted before importing.

Solutions:

1. Import with Force

   drush cim -y --partial
   

2. Delete Conflicting Entities

   drush entity:delete view view_name
   drush cim -y
   

3. Sync Configuration Manually

   • Visit /admin/config/development/configuration
   • Review and import specific changes

Need more help? See Debugging Techniques or Get Support.

5 - Activity Finder Issues

Having trouble with Activity Finder? Find solutions to common integration issues below.

API Connection Failures

Error: Could not connect to Daxko/ActiveNet/Personify API

Solutions:

1. Check API Credentials

   • Visit /admin/openy/integrations/activity-finder
   • Re-enter API key and secret
   • Test connection

2. Check Firewall

   # Test API endpoint
   curl -I https://api.daxko.com/
   

3. Check Logs

   drush watchdog:show --severity=Error | grep activity
   

4. Contact CRM Provider

   • Verify API credentials with Daxko/ActiveNet/Personify
   • Check for API endpoint changes

Programs Not Displaying

Problem: Activity Finder shows no programs.

Solutions:

1. Check Mapping

   • Visit /admin/openy/integrations/activity-finder/mapping
   • Ensure categories are mapped

2. Clear Cache

   drush cr
   drush cron
   

3. Check API Response

   drush watchdog:tail
   # Visit Activity Finder page and watch for errors
   

Need more help? See Debugging Techniques or Get Support.

6 - Debugging Techniques

Learn how to effectively debug issues in YMCA Website Services using these essential techniques and tools.

Enable Verbose Error Messages

// In settings.local.php (development only)
$config['system.logging']['error_level'] = 'verbose';

Use Drush for Debugging

# Watch logs in real-time
drush watchdog:tail

# Show recent errors
drush watchdog:show --severity=Error --count=20

# Check site status
drush status

# Check for security updates
drush pm:security

Browser Developer Tools

1. Network Tab - Check for failed requests
2. Console Tab - Check for JavaScript errors
3. Application Tab - Check cookies and local storage

Enable Twig Debugging

# In sites/default/services.yml
parameters:
  twig.config:
    debug: true
    auto_reload: true
    cache: false

Then clear cache: drush cr

Need more help? See specific error categories or Get Support.