wp-agentic-writer/GENERATION_HANG_DEBUG.md

# Generation Hang Issue - Debugging Steps

## Problem Report

User submitted Indonesian prompt:
```
cara membuat toko online dengan wordpress cukup dengan page builder tanpa plugin ecommerce, cukup dengan katalog, single page dan tombol click to whatsapp. Sertakan juga cara membuat link whatsapp yang dynamic dengan menyesuaikan isi template pesan menyebutkan nama produknya (post_title)
```

**Observed Behavior:**
- No clarification quiz appeared (correct - prompt is detailed enough)
- Status changed to "Generating article..."
- Generation hung/stuck at this point
- No content was generated

---

## What I've Added

### 1. Frontend Timeout Detection (assets/js/sidebar.js)

Added a **2-minute timeout** for article generation:
- If no response received within 120 seconds, shows timeout error
- Automatically cancels the hanging request
- Displays user-friendly error message

**Location:** Lines 660-672
```javascript
// Add timeout to detect hanging responses
const timeout = setTimeout( () => {
    if ( isLoading ) {
        console.error( 'Generation timeout - no response received' );
        setMessages( prev => [ ...prev, {
            role: 'system',
            type: 'error',
            content: 'Request timeout. The AI is taking too long to respond. Please try again.'
        } ] );
        setIsLoading( false );
        reader.cancel();
    }
}, 120000 ); // 2 minute timeout
```

### 2. Backend Logging (includes/class-gutenberg-sidebar.php)

Added error logging at critical points to identify where the hang occurs:

**Plan Generation Logging (Lines 608-614):**
```php
// Log the request for debugging
error_log( 'WP Agentic Writer: Calling OpenRouter API for planning. Topic: ' . substr( $topic, 0, 100 ) );
error_log( 'WP Agentic Writer: Detected language: ' . $detected_language );

$response = $provider->chat( $messages, array( 'temperature' => 0.7 ), 'planning' );

error_log( 'WP Agentic Writer: OpenRouter API response received' );
```

**Article Generation Logging (Lines 823-848):**
```php
// Log before calling streaming API
error_log( 'WP Agentic Writer: Starting section generation: ' . $section['heading'] );

// ... code ...

error_log( 'WP Agentic Writer: Calling OpenRouter streaming API' );

$response = $provider->chat_stream( ... );
```

---

## How to Debug

### Step 1: Enable WordPress Debug Logging

Add to `wp-config.php`:
```php
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
```

### Step 2: Reproduce the Issue

1. Open the WordPress editor
2. Submit the same Indonesian prompt
3. Wait for the timeout (2 minutes) or note when it hangs

### Step 3: Check Debug Log

The debug log is located at:
```
/wp-content/debug.log
```

Look for these log entries:
- `WP Agentic Writer: Calling OpenRouter API for planning`
- `WP Agentic Writer: Detected language: indonesian`
- `WP Agentic Writer: OpenRouter API response received`
- `WP Agentic Writer: Starting section generation: ...`
- `WP Agentic Writer: Calling OpenRouter streaming API`

### Step 4: Identify the Hang Point

**If you see:**
```
WP Agentic Writer: Calling OpenRouter API for planning
```

**But NOT:**
```
WP Agentic Writer: OpenRouter API response received
```

→ **Issue:** Plan generation API call is hanging

**If you see:**
```
WP Agentic Writer: Starting section generation: ...
WP Agentic Writer: Calling OpenRouter streaming API
```

**But no content appears**

→ **Issue:** Article generation streaming API is hanging

---

## Common Causes & Solutions

### Cause 1: OpenRouter API Timeout

**Symptoms:**
- Log shows API call started but no response
- Takes longer than 30-60 seconds

**Solution:**
- Check OpenRouter API status: https://status.openrouter.ai/
- Verify API key is valid in settings
- Try a different model (shorter prompt, simpler request)

### Cause 2: PHP Execution Timeout

**Symptoms:**
- Script dies after max_execution_time
- PHP fatal error in logs

**Solution:**
Add to `wp-config.php`:
```php
set_time_limit( 300 ); // 5 minutes
@ini_set( 'max_execution_time', 300 );
```

### Cause 3: Memory Limit

**Symptoms:**
- "Allowed memory size exhausted" error
- Script terminates unexpectedly

**Solution:**
Add to `wp-config.php`:
```php
define( 'WP_MEMORY_LIMIT', '512M' );
```

### Cause 4: Network/Blocking Issues

**Symptoms:**
- Timeout happens immediately
- No logs at all

**Solution:**
- Check firewall/security plugin settings
- Verify server can reach api.openrouter.ai
- Check for CDN/caching interference

### Cause 5: Prompt Too Complex

**Symptoms:**
- Works with simple prompts
- Hangs with complex Indonesian prompt

**Solution:**
- Break into smaller requests
- Use quiz to gather requirements first
- Simplify the prompt structure

---

## Testing Checklist

### Basic Tests:
- [ ] Simple English prompt: "Write about SEO"
- [ ] Simple Indonesian prompt: "Tulis tentang SEO"
- [ ] Medium complexity prompt
- [ ] Complex prompt (like the user's)

### Diagnostic Tests:
- [ ] Check debug.log after each test
- [ ] Note which log entries appear
- [ ] Measure time to hang/timeout
- [ ] Check browser console for errors
- [ ] Check Network tab in DevTools

### API Tests:
- [ ] Verify OpenRouter API key works
- [ ] Test API directly with curl:
```bash
curl -X POST https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-3-haiku",
    "messages": [{"role": "user", "content": "Say hello"}]
  }'
```

---

## Next Steps

1. **Enable debug logging** in wp-config.php
2. **Reproduce the issue** with the same Indonesian prompt
3. **Check debug.log** for the sequence of log entries
4. **Identify where it hangs** (planning or generation)
5. **Share the log contents** so we can pinpoint the exact issue

The logs will tell us:
- Is the language detection working?
- Is the planning API call completing?
- Is the article generation starting?
- Where exactly does it hang?

---

**Files Modified:**
1. [assets/js/sidebar.js](assets/js/sidebar.js) - Added 2-minute timeout
2. [includes/class-gutenberg-sidebar.php](includes/class-gutenberg-sidebar.php) - Added debug logging

**Status:** ⏳ Awaiting debug log information from user