CDN_DIAGNOSTICS.md

WebLLM CDN Diagnostics & Troubleshooting

Issue: "WebLLM library is still loading from CDN. Please wait..."

This message appears when the CDN takes longer than expected to load. This guide helps you troubleshoot.

---

Quick Diagnostic (Copy-Paste to Console)

Open https://snapkittywest.github.io/rowm-polymorphic-notebook/index-app.html, press F12, then paste:

// Check CDN loading status
console.log('=== WebLLM CDN Status ===');
console.log('Ready:', window.webllmReady);
console.log('Loading:', window.webllmCDNLoading);
console.log('Error:', window.webllmError);
console.log('Library type:', typeof window.webllm);
console.log('Load time (ms):', window.webllmLoadTimestamp ? Date.now() - window.webllmLoadTimestamp : 'N/A');

// If loaded, show MLCEngine
if (window.webllm && window.webllm.MLCEngine) {
    console.log('MLCEngine available:', typeof window.webllm.MLCEngine);
} else if (window.webllm) {
    console.log('WebLLM loaded but MLCEngine not found');
} else {
    console.log('WebLLM not loaded yet');
}

Expected Output (Success):

Ready: true
Loading: false
Error: null
Library type: object
Load time: 2500 (milliseconds)
MLCEngine available: function

Expected Output (Slow Loading):

Ready: false
Loading: true
Error: null
Library type: undefined
Load time: 8500
MLCEngine available: N/A

---

Network Tab Analysis

1. Open DevTools > Network tab
2. Reload page (F5)
3. Look for: web-llm.js request

Check the following:

Item	Good	Bad	Fix
Status	200, 304	404, 403, 0	Check CDN URL or internet
Time	<5s	>10s	CDN slow, try unpkg fallback
Size	1.5MB	Much larger	File corrupted, retry
CORS	No error	CORS error	Network/firewall blocking

CDN URLs Used (in order):

1. Primary: https://cdn.jsdelivr.net/npm/@mlc-ai/web-llm@0.2.32/dist/web-llm.js
2. Fallback: https://unpkg.com/@mlc-ai/web-llm@0.2.32/dist/web-llm.js

---

Common Issues & Solutions

Issue 1: CDN Loads But Takes 10+ Seconds

Symptoms:

• Console shows: Ready: false, Loading: true for >10 seconds
• Network tab shows: Status 200 but very slow transfer

Causes:

• Slow internet connection
• CDN server responding slowly
• Large file size (1.5MB)

Solutions:

// Option A: Force retry from backup CDN
window.retryWebLLMLoad();

// Option B: Wait longer (CDN may still load)
// Just wait 30 more seconds, then try LOAD LOCAL MODEL again

Issue 2: CDN Request Times Out (No Response)

Symptoms:

• Console shows: Error: jsDelivr timeout
• Network tab shows: CDN request pending indefinitely or canceled

Causes:

• Network timeout (CDN unreachable)
• Firewall/proxy blocking CDN
• ISP throttling or filtering

Solutions:

// Automatic: Fallback to unpkg triggers after 8 seconds
// Manual retry:
window.retryWebLLMLoad();

// If still fails, try from corporate WiFi or personal hotspot

Issue 3: CORS Error

Symptoms:

• Console shows: Access to XMLHttpRequest from 'file://...' has been blocked by CORS policy
• Or: Access to fetch from 'https://cdn.jsdelivr.net' blocked by CORS

Causes:

• Opening file:// directly (not via HTTP server)
• Corporate proxy filtering cross-origin requests

Solutions:

// Must use HTTP/HTTPS, not file://
// Visit: https://snapkittywest.github.io/rowm-polymorphic-notebook/index-app.html
// NOT: file:///C:/Users/.../index-app.html

// If corporate network:
// 1. Ask IT to whitelist: cdn.jsdelivr.net
// 2. Try from personal WiFi/hotspot
// 3. Use VPN if allowed

Issue 4: WebLLM Loads But window.webllm Is undefined

Symptoms:

• Network tab shows: 200 (file downloaded)
• Console shows: typeof window.webllm: undefined

Causes:

• Script loaded but didn't execute properly
• File corrupted or wrong version
• Browser doesn't support WASM or async

Solutions:

// Manually retry:
window.retryWebLLMLoad();

// Check browser compatibility:
console.log('WebAssembly:', typeof WebAssembly !== 'undefined');
console.log('Promise:', typeof Promise !== 'undefined');
console.log('Symbol.asyncIterator:', Symbol.asyncIterator);

Issue 5: "Please Wait..." Message Never Disappears

Symptoms:

• Message: "WebLLM library is still loading from CDN. Please wait..."
• Appears indefinitely, button doesn't re-enable

Causes:

• CDN truly stuck (not responding)
• Browser timeout setting too high
• JavaScript error preventing completion

Solutions:

// Try manual retry:
window.retryWebLLMLoad();

// Check for JavaScript errors:
// Press F12, look for red errors in Console

// Force manual timeout:
setTimeout(function() {
    console.log('Manual timeout fired');
    if (!window.webllm) {
        console.log('CDN still not loaded after 30 seconds, giving up');
        window.webllmError = 'Timeout after 30 seconds';
        window.webllmCDNLoading = false;
        // Click LOAD LOCAL MODEL button to show error
    }
}, 30000);

---

Manual Retry Steps

When to use: If "Please wait..." message persists for >15 seconds

1. Open Console (F12)
2. Paste: window.retryWebLLMLoad()
3. Wait 5-10 seconds
4. Check console for: "WebLLM loaded from unpkg"
5. Try clicking "LOAD LOCAL MODEL" button again

Expected result:

• Console shows: WebLLM loaded from unpkg X milliseconds
• Status in Ahmad Bot changes from OFFLINE to READY

---

Browser Console Command Reference

Command	Purpose	Expected Output
window.webllmReady	Check if loaded	true
typeof window.webllm	Check library exists	object
window.webllmError	Show error reason	null or error text
Date.now() - window.webllmLoadTimestamp	Check load time (ms)	2500 (normal) or >10000 (slow)
window.retryWebLLMLoad()	Manual retry	Loads from unpkg
window.initAhmadUI()	Re-initialize UI	No visible change
window.ahmadJITUI.updateStatus('READY')	Force status change	Status badge changes

---

Network Conditions to Test

These represent different scenarios:

// Test 1: Slow CDN (simulates poor connection)
// Just wait longer (15+ seconds expected)

// Test 2: Timeout scenario
// CDN doesn't respond after 8 seconds → Fallback to unpkg

// Test 3: Corporate network
// May be blocked by proxy → Try personal WiFi

// Test 4: Mobile hotspot
// May have data limits → Download may be slow (5-10 min)

---

Expected CDN Load Times

Connection	Expected Time	Timeout
Fiber (100+ Mbps)	2-3 seconds	8 seconds
Broadband (10-50 Mbps)	3-5 seconds	8 seconds
DSL (3-10 Mbps)	5-10 seconds	8 seconds
Mobile 4G (5-20 Mbps)	5-15 seconds	8 seconds
Mobile 3G (<5 Mbps)	15-30 seconds	8 seconds (fallback)
Satellite	30+ seconds	8 seconds (fallback)

Note: If CDN takes >8 seconds, automatic fallback to unpkg triggers.

---

Full Diagnostic Report (Copy-Paste Everything)

Paste this entire script in console to get a complete report:

console.log('=== WebLLM CDN FULL DIAGNOSTIC REPORT ===');
console.log('Timestamp:', new Date().toISOString());
console.log('');
console.log('=== Library Status ===');
console.log('window.webllm:', typeof window.webllm);
console.log('window.webllmReady:', window.webllmReady);
console.log('window.webllmCDNLoading:', window.webllmCDNLoading);
console.log('window.webllmError:', window.webllmError);
console.log('');
console.log('=== Performance ===');
console.log('Load time (ms):', window.webllmLoadTimestamp ? Date.now() - window.webllmLoadTimestamp : 'Not started');
console.log('');
console.log('=== MLCEngine ===');
if (window.webllm) {
    console.log('MLCEngine available:', typeof window.webllm.MLCEngine);
    console.log('MLCEngine is function:', typeof window.webllm.MLCEngine === 'function');
} else {
    console.log('WebLLM not loaded, cannot check MLCEngine');
}
console.log('');
console.log('=== Browser Support ===');
console.log('WebAssembly:', typeof WebAssembly);
console.log('Promise:', typeof Promise);
console.log('Async/Await:', typeof (async function(){}).constructor);
console.log('');
console.log('=== Recommendations ===');
if (window.webllmReady) {
    console.log('✓ WebLLM is ready. Try clicking LOAD LOCAL MODEL.');
} else if (window.webllmCDNLoading) {
    console.log('⟳ WebLLM still loading. Wait a moment and try again.');
    console.log('  OR manually retry: window.retryWebLLMLoad()');
} else if (window.webllmError) {
    console.log('✗ WebLLM failed to load. Error:', window.webllmError);
    console.log('  Trying manual retry: window.retryWebLLMLoad()');
} else {
    console.log('? WebLLM status unknown. Try refreshing the page.');
}

---

Still Having Issues?

Try these in order:

1. Hard Refresh — Ctrl+Shift+R (Windows) / Cmd+Shift+R (Mac)
2. Clear Cache — DevTools > Settings > Network > Disable cache (checked)
3. Manual Retry — Paste: window.retryWebLLMLoad()
4. Different Browser — Try Chrome, Firefox, Safari, Edge
5. Different Network — Try phone hotspot or different WiFi
6. Check Internet — Open google.com, YouTube, etc. to confirm connection works

---

For Developers

Key Variables:

• window.webllmReady — Boolean, true when library loaded
• window.webllmError — String, error reason if failed
• window.webllmCDNLoading — Boolean, true while loading
• window.webllmLoadTimestamp — Number, when loading started (Date.now())
• window.webllmCallbacks — Array, functions to call when ready

Key Functions:

• window.retryWebLLMLoad() — Manual fallback to unpkg
• window.onWebLLMReady(callback) — Register callback for when ready
• window.fireWebLLMCallbacks() — Internal, fires all callbacks

CDN Load Timeout: 8 seconds (after which fallback triggers)

---

Last Updated: July 27, 2026
Page: https://snapkittywest.github.io/rowm-polymorphic-notebook/index-app.html