# FAQPage Schema Production Debugging Guide

**Date:** 2026-01-15  
**Status:** Pages Loading ✅ | FAQPage Schema Missing ⚠️

## Current Status

### ✅ Working
- All blog post pages load successfully (HTTP 200)
- FAQ sections render correctly (10 FAQs per page)
- HTML structure is valid
- No PHP errors detected

### ⚠️ Issue
- FAQPage schema is not being generated in production
- Schema graph contains 5 items instead of 6 (missing FAQPage)
- Local testing shows FAQPage schema generates correctly

## Enhanced Logging Added

Added comprehensive error logging to `v2/config/blog-schema-generator.php`:

1. **Schema Generation Start:**
   - Logs when FAQs are detected in overrides
   - Logs FAQ count and validation status

2. **FAQ Processing:**
   - Logs each FAQ being processed
   - Logs skipped FAQs with reasons
   - Logs processing results (processed vs skipped)

3. **FAQPage Addition:**
   - Logs when FAQPage schema is successfully added
   - Verifies FAQPage exists in @graph after addition
   - Logs warning if FAQPage should exist but doesn't

4. **Error Handling:**
   - Logs exceptions with full stack traces
   - Logs fatal errors with stack traces
   - Logs when FAQs are not provided or invalid

## Debugging Steps

### 1. Check Production Error Logs

After deployment, check PHP error logs for messages starting with:
- `Schema generation for`
- `FAQPage schema:`

**Expected logs if working:**
```
Schema generation for https://www.ordio.com/insights/lexikon/vaterschaftsurlaub/: FAQs in overrides: yes (10), FAQs variable: count=10, is_array=1, empty=
FAQPage schema generation started for https://www.ordio.com/insights/lexikon/vaterschaftsurlaub/ with 10 FAQs
FAQPage schema: Processed 10 FAQs, skipped 0 FAQs
FAQPage schema: Successfully added FAQPage schema with 10 FAQs to @graph (total items: 6)
```

**If not working, look for:**
- `No valid FAQs for` - FAQs not being passed correctly
- `Exception generating FAQPage schema` - Error during generation
- `No valid FAQ items to add` - All FAQs filtered out

### 2. Clear PHP Opcache

If code was deployed but changes aren't appearing:

```bash
# Restart PHP-FPM (method depends on server setup)
sudo systemctl restart php-fpm
# OR
sudo service php-fpm restart

# Or clear opcache via PHP
php -r "opcache_reset();"
```

### 3. Verify Code Deployment

Check that the following files are deployed with latest changes:
- `v2/config/blog-schema-generator.php` - Should have enhanced logging
- `v2/pages/blog/post.php` - Should pass FAQs to schema generator
- `v2/components/blog/BlogFAQ.php` - Should have error handling

### 4. Test Schema Generation Directly

Create a test script on production server:

```php
<?php
// test-schema-production.php
require_once 'v2/config/blog-template-helpers.php';
require_once 'v2/config/blog-schema-generator.php';

$post = load_blog_post('lexikon', 'vaterschaftsurlaub');
$schema_overrides = ['faqs' => $post['faqs'] ?? []];

$schema = generate_blog_schema('post', $post, $schema_overrides);

$has_faqpage = false;
if (isset($schema['@graph'])) {
    foreach ($schema['@graph'] as $item) {
        if (isset($item['@type']) && $item['@type'] === 'FAQPage') {
            $has_faqpage = true;
            echo "✅ FAQPage found with " . count($item['mainEntity']) . " FAQs\n";
            break;
        }
    }
}

if (!$has_faqpage) {
    echo "❌ FAQPage NOT found\n";
    echo "Schema @graph items: " . count($schema['@graph']) . "\n";
}
```

Run on production: `php test-schema-production.php`

## Validation Scripts

Use these scripts to validate production:

```bash
# Comprehensive validation
php v2/scripts/blog/validate-production-comprehensive.php

# Schema-specific validation
php v2/scripts/blog/validate-schema-production.php

# Final validation
php v2/scripts/blog/final-production-validation.php
```

## Possible Root Causes

1. **PHP Opcache:** Stale code cached
2. **Code Not Deployed:** Latest changes not on production server
3. **Silent Error:** Exception being caught but not logged properly
4. **FAQs Not Passed:** FAQs not being passed to schema generator correctly
5. **Production Environment:** PHP version or extension differences

## Next Steps

1. ✅ Check production error logs for FAQPage schema messages
2. ✅ Clear PHP opcache
3. ✅ Verify code deployment
4. ✅ Run test script on production server
5. ✅ Re-test production URLs after fixes

## Related Files

- `v2/config/blog-schema-generator.php` - Schema generation with enhanced logging
- `v2/pages/blog/post.php` - Post template that calls schema generator
- `v2/scripts/blog/validate-production-comprehensive.php` - Validation script
- `docs/content/blog/PRODUCTION_VALIDATION_REPORT.md` - Validation report