# Blog FAQ Troubleshooting Guide

**Last Updated:** 2026-01-15

## Common Issues

### HTTP 500 Errors on Posts with FAQs

**Symptoms:**
- Blog posts with FAQs return HTTP 500 errors in production
- Blog posts without FAQs load correctly
- Error occurs during FAQ rendering or schema generation

**Diagnosis:**

1. **Check PHP Error Logs:**
   ```bash
   # Look for errors related to:
   # - extract_faq_topic function redefinition
   # - sanitizeHtmlOutput function not found
   # - FAQ schema generation errors
   # - JSON encoding errors
   ```

2. **Run Diagnostic Scripts:**
   ```bash
   # Test specific failing posts
   php v2/scripts/blog/test-faq-rendering.php
   
   # Diagnose all posts with FAQs
   php v2/scripts/blog/diagnose-all-faqs.php
   
   # Validate FAQ structure
   php v2/scripts/blog/validate-faq-posts.php
   ```

**Solutions:**

1. **Function Redefinition Errors:**
   - Ensure `extract_faq_topic` has `function_exists` check
   - Verify `BlogFAQ.php` is only included once per page

2. **Missing Functions:**
   - Verify `sanitizeHtmlOutput` is defined in `blog-template-helpers.php`
   - Check function is loaded before FAQ component

3. **Invalid FAQ Data:**
   - Validate FAQ structure (must have 'question' and 'answer' keys)
   - Check for empty questions or answers
   - Verify FAQs array is properly formatted

4. **Encoding Issues:**
   - Ensure UTF-8 encoding throughout
   - Check for invalid characters in FAQ answers
   - Verify HTML entities are properly decoded

### FAQ Section Not Rendering

**Symptoms:**
- FAQ section doesn't appear on page
- No errors in logs
- FAQs exist in JSON file

**Diagnosis:**

1. Check if FAQs array is empty:
   ```php
   var_dump($post_faqs); // Should show array with FAQs
   ```

2. Verify FAQ component is included:
   ```php
   // Check post.php includes BlogFAQ.php
   ```

3. Check FAQ validation logic:
   ```php
   // FAQs are filtered for validity before rendering
   ```

**Solutions:**

1. Verify FAQs in JSON file are properly structured
2. Check FAQ validation doesn't filter out valid FAQs
3. Ensure FAQ component file exists and is readable

### FAQ Schema Not Generating

**Symptoms:**
- FAQPage schema missing from page source
- Schema validation fails
- FAQs exist but schema doesn't

**Diagnosis:**

1. Check schema generation:
   ```bash
   php v2/scripts/blog/test-faq-rendering.php
   ```

2. Verify FAQs are passed to schema generator:
   ```php
   // Check $schema_overrides['faqs'] is set
   ```

**Solutions:**

1. Ensure FAQs are validated before schema generation
2. Check JSON encoding works correctly
3. Verify FAQ structure matches expected format

## Testing & Validation

### Pre-Deployment Checklist

1. **Run Diagnostic Script:**
   ```bash
   php v2/scripts/blog/diagnose-all-faqs.php
   ```
   Should show: `✅ All FAQ posts passed validation`

2. **Run Validation Script:**
   ```bash
   php v2/scripts/blog/validate-faq-posts.php
   ```
   Should exit with code 0

3. **Test Edge Cases:**
   ```bash
   php v2/scripts/blog/test-faq-edge-cases.php
   ```
   All tests should pass

4. **Test Failing Posts:**
   ```bash
   php v2/scripts/blog/test-faq-rendering.php
   ```
   All posts should pass

### Production Testing

1. Test failing URLs:
   - `/insights/ratgeber/fehler-digitalisierung-gastronomie/`
   - `/insights/lexikon/vaterschaftsurlaub/`
   - `/insights/lexikon/lohnabrechnung/`

2. Verify:
   - Page loads without HTTP 500 error
   - FAQ section renders correctly
   - FAQPage schema is present
   - No console errors

3. Check error logs:
   - No FAQ-related errors
   - No function redefinition errors
   - No encoding errors

## Error Handling

### Current Error Handling

1. **Schema Generation:**
   - Try-catch around FAQ processing
   - Individual FAQ error handling
   - Continues processing on errors
   - Logs errors without breaking page

2. **FAQ Component:**
   - Function existence checks
   - Try-catch around sanitization
   - Fallback rendering
   - Validates input before processing

3. **Post Template:**
   - Validates FAQ structure
   - Filters invalid FAQs
   - Error handling around FAQ section
   - Fallback rendering if component fails

### Best Practices

1. Always validate FAQ structure before processing
2. Use function_exists checks for functions defined in components
3. Wrap FAQ processing in try-catch blocks
4. Log errors without exposing to users
5. Provide fallback rendering when possible
6. Test with production-like error reporting

## Related Files

- `v2/pages/blog/post.php` - Post template with FAQ rendering
- `v2/components/blog/BlogFAQ.php` - FAQ component
- `v2/config/blog-schema-generator.php` - Schema generation
- `v2/config/blog-template-helpers.php` - Helper functions
- `v2/scripts/blog/test-faq-rendering.php` - Test script
- `v2/scripts/blog/diagnose-all-faqs.php` - Diagnostic script
- `v2/scripts/blog/validate-faq-posts.php` - Validation script