Skip to content

Troubleshooting

Jump to bottom
Alee Javed edited this page Mar 1, 2026 · 1 revision

Troubleshooting

Common issues and solutions for the Aleejaved Portfolio WordPress theme.

🚀 Installation Issues

Theme Not Showing

Problem: Theme appears in admin but not on site

Solutions:

  1. Check theme folder - Ensure aleejaved-portfolio folder exists in /wp-content/themes/
  2. Verify permissions - Folders should be 755, files 644
  3. Check WordPress version - Requires WordPress 5.0+
  4. Activate theme - Go to Appearance → Themes and activate
  5. Clear cache - Browser and WordPress cache

White Screen of Death

Problem: Site loads blank after theme activation

Solutions:

  1. Check PHP errors - Enable debug mode in wp-config.php
  2. Increase memory - Set WP_MEMORY_LIMIT to 256M
  3. Check plugins - Deactivate all plugins temporarily
  4. Verify functions.php - Ensure file is complete
  5. Rollback theme - Switch to default theme temporarily

Missing Features

Problem: Theme features not working (buttons, timeline, etc.)

Solutions:

  1. Check JavaScript - Ensure scripts are loading
  2. Verify assets - Check /assets/ folder
  3. Clear cache - Browser and WordPress cache
  4. Check console - Look for JavaScript errors
  5. Test individually - Enable features one by one

🎨 Styling Issues

Colors Not Applying

Problem: Customizer colors not showing

Solutions:

  1. Clear cache - Browser cache (Ctrl+F5) and WordPress cache
  2. Check variables - Ensure CSS variables are loading
  3. Verify Customizer - Check if settings are saved
  4. Test different browsers - Try Chrome, Firefox, Safari
  5. Check CSS file - Ensure aleejaved_portfolio_custom_css() function exists

Navigation Issues

Problem: Navigation not showing or styled incorrectly

Solutions:

  1. Check page count - Ensure you have 2+ published pages
  2. Verify menu order - Check Pages → Page Order
  3. Clear cache - Browser and WordPress cache
  4. Check CSS - Ensure navigation styles are loading
  5. Test responsive - Check different screen sizes

Hero Section Problems

Problem: Hero text not displaying or styled incorrectly

Solutions:

  1. Check front-page.php - Ensure hero section exists
  • Check Customizer - Verify hero settings
  • Clear cache - Browser and WordPress cache
  • Test responsive - Check different screen sizes
  • Check images - Verify featured image is set

Button Issues

Problem: Buttons not styled or not working

Solutions:

  1. Check CSS - Ensure button styles are loading
  • Verify variables - Check accent color variable
  • Test hover - Check hover states
  • Clear cache - Browser and WordPress cache
  • Check JavaScript - Ensure button interactions work

🔧 Feature-Specific Issues

Timeline Not Working

Problem: Timeline not showing or sorting incorrectly

Solutions:

  1. Check posts - Ensure posts have "timeline" category
  • Verify settings - Check Timeline → Timeline Order
  • Clear cache - Browser and WordPress cache
  • Check JavaScript - Ensure timeline.js is loading
  • Test filters - Ensure category filtering works

Birthday Cards Not Working

Problem: Cards not showing or animations broken

Solutions:

  1. Check posts - Ensure cards are published
  • Verify template - Check single-aj_card.php
  • Clear cache - Browser and WordPress cache
  • Check JavaScript - Ensure card animations work
  • Test images - Verify image uploads

Popups Not Working

Problem: Popups not appearing or not functioning

Solutions:

  1. Check posts - Ensure popups are published
  • Verify template - Check popup output function
  • Clear cache - Browser and WordPress cache
  • Check JavaScript - Ensure popup.js is loading
  • Test triggers - Ensure popup triggers work

Page Order Not Working

Problem: Page order interface not working

Solutions:

  1. Check JavaScript - Ensure page-order-admin.js is loading
  • Verify interface - Check admin interface loads
  • Test drag and drop - Try reordering pages
  • Check save function - Ensure AJAX save works
  • Clear cache - Browser and WordPress cache

📱 Responsive Issues

Mobile Layout Problems

Problem: Site not displaying correctly on mobile

Solutions:

  1. Check breakpoints - Test at different screen sizes
  • Verify media queries - Ensure responsive CSS is working
  • Test touch targets - Ensure buttons are touch-friendly
  • Check navigation - Test mobile menu
  • Clear cache - Browser and WordPress cache

Font Issues

Problem: Fonts not displaying correctly

Solutions:

  • Check font loading - Ensure fonts are loading properly
  • Test different browsers - Try Chrome, Firefox, Safari
  • Clear cache - Browser and WordPress cache
  • Check CSS - Ensure font styles are loading
  • Verify units - Use responsive font sizes

🔍 Debugging Tools

Browser Developer Tools

  1. Open Developer Tools (F12)
  2. Check Console - Look for JavaScript errors
  3. Inspect Elements - Check CSS variables
  4. Network Tab - Check file loading
  5. Performance Tab - Check loading speed

WordPress Debug Mode

Add to wp-config.php:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', true);

Error Logging

Add to functions.php:

error_log('Theme Error: ' . $error_message);

🆘 Common Solutions

Clear Cache

# WordPress cache
wp cache flush

# Browser cache
# Chrome: Ctrl+Shift+R
# Firefox: Ctrl+F5
# Safari: Cmd+Shift+R

Reset Theme

  1. Switch to default theme temporarily
  2. Reactivate your theme
  3. Re-save Customizer settings
  4. Clear all caches

Check File Integrity

  1. Verify functions.php - Ensure file is complete
  2. Check style.css - Ensure styles are present
  3. Verify assets - Ensure JavaScript files exist
  4. Check templates - Ensure all PHP files are present

Plugin Conflicts

  1. Deactivate all plugins
  2. Reactivate theme
  3. Activate plugins one by one
  4. Identify conflicting plugin

📞 Support Resources

Getting Help

  1. Check this wiki - Browse all documentation
  2. Search issues - Look for similar problems
  3. Create issue - Report new problem
  4. Start discussion - Ask community for help

Creating Issues

  1. Be specific - Include exact error messages
  2. Provide details - Browser, WordPress version, plugins
  3. Include screenshots - Show the problem
  4. List steps - What you've tried

Community Support

  • GitHub Issues - Report bugs and problems
  • WordPress Forums - Get help from community
  • Theme Developer - Contact theme author

📚 Related Documentation

Clone this wiki locally