ComusThumbz Troubleshooting
ComusThumbz Troubleshooting Guide
Versiyon: 1.0.0
Oluşturun: 2026-02-03
Applies to: ComusThumbz CMS - Tamam Backend & Frontend
İçerik tablosu
- Genel Bakış
- Hızlı Tanı Checklist
- Server & PHP Hataları
- Database Issues
- Video İşleme
- API Issues
- Frontend Issues
- Cam Performers System
- Canlı Akış (LiveKit)
- Yaratıcı Monetization
- Kimlik ve Kullanıcılar
- Cron Jobs
- Debug Tools Referans
- Log File Locations
- Common SQL Fixes
Genel Bakış
Bu kılavuz, ComusThumbz CMS için bilgi sorun gidermeyi konsolide eder, hem arka uç yönetim panelini kapsar (ct/admin/) ve ön halk sayfaları (proje kökü). Sorunlar belirtiler, nedenler ve çözümlerle kategori tarafından düzenlenir.
Hızlı Tanı Checklist
Herhangi bir sorunla karşılaşıldığında bu kontroller aracılığıyla hareket edin:
- PHP hatası log - Check-
ct/logs/Ve sunucunuzun PHP hatası son hataları için oturum açma - Cron işleri -Köpek işlerinizi onaylayın (çoğu "data'yı güncellemez" sorunları)
- Dosya izinleri - Web sunucusu okuma / yazma erişimine sahip olmalıdır
uploads/,ct/logs/,ct/dat/ - Veritabanı bağlantısı - Test with
https://yourdomain.com/tools/simpletest.php?key=comus2025 - API sağlık - Test with
https://yourdomain.com/ct/api/v1/features - Özel toggles - Engelli özellikler, "sayfayı göstermeme" en yaygın nedenidir.
- Tarayıcı konsolu - JavaScript hataları için kontrol (F12 -> Console)
- Network sekmesi - Başarısız API talepleri için kontrol (F12 -> Network)
Server & PHP Hataları
Blank Page / 500 Internal Server Hata
Ortak Sebepler:
declare(stricttypes=1)yerleştirme yerleştirme yerleştirme yerleştirme yerleştirme yerleştirme yerleştirme yerleştirme yerleştirme yerleştirme yerleştirme yerleştirme - Daha sonra ilk çizgi olmalıdırHerhangi bir beyaz uzay, BOM karakteri veya kod ölümcül bir hataya neden oluyor.
- PHP syntax hatası - Hata logunu kontrol edin:
- Eksiklik dosya dosyası içerir - A
requireonceMevcut olmayan bir dosya için:
- Ekran hataları engelli - Temporly debugging için etkinleştirin:
Çözüm: PHP hatasını ilk önce kontrol edin. Boş olursa, etkinleştirin
displayerrors Geçici olarak gerçek hatayı görmek.Admin Dili Singleton Hata
Fatal error: Cannot instantiate AdminLanguage veya yönetici sayfalarında 500 hata.Çünkü: Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using Using
new AdminLanguage() Tekton deseni yerine.Fix:
Memory Limit E tükenmiş
Fatal error: Allowed memory size of X bytes exhaustedOrtak tetikleyiciler:
- Büyük video dosyası yükler
- Büyük görüntü galerileri
- 400K+ cam performans kayıtları
Çözüm: PHP hafıza limitini artırmak:
Ya da per-script:
Max Execution Time Exceed
Fatal error: Maximum execution time of 30 seconds exceededOrtak tetikleyiciler:
- Video işleme cron işleri
- Büyük veritabanı sorguları
- Dış API, zamanlamayı çağırır
Çözüm:
Sahte işler için, sınırsız ayarlama:
Dosya İzin Hataları
Permission denied dosyaları yazarken veya yönetmenler oluştururken hatalar.Gerekli izinler:
Fix:
Database Issues
Veritabanı Bağlantı Başarısız
Tanı:
- Hızlı veritabanı aracı ile test:
- Güvenilirliği doğrulayın
ct/dat/config.inc.php:
- Check Natasha çalışıyor:
Çözüm: Verify Natasha hizmeti çalıştırılır ve veritabanı yapılandırmasını eşleştirir.
Masa Locks & Blocking Queries
Tanı:
- Natasha Status aracını çalıştırın:
- Soruları engellemek için kontrol edin:
30 saniyeden uzun süren sorgulara bakın.
- Database Lock Inspector For InnoDB kilit analizi için kullanın:
Çözüm:
- bloke sorguyu öldür:
- Ya da debug aracı aracılığıyla:
Ortak suçlu: The The The The The The The The
apicron.php marksiteperformersoffline() Tüm performansçıları bir anda güncelle. Bu, toplu güncellemelerle düzeltildi (10ms durakları ile bir seferde 1000 sıra).Yavaş Queries
Tanı:
Çözüm:
- Regify indexler sık sık sütunlu sütunlarda bulunur
- Use Use Use Use Use Use
EXPLAINKayıp indeksleri tanımlamak için yavaş sorgular - APCu önbelleği çalışıyorsa kontrol edin (
php -m | grep apcu) - Cam sanatçılar için, kullanın
?fast=1COUNT sorgularının atılması
SQL Debugging Komutları
Video İşleme
Video Stuck at 'pending'
Bu en yaygın video konusu. Bunu sırayla kontrol edin:
- Cron işleri çalışmıyor - Video işlemci bir program üzerinde çalışır:
- php /path/to/ct/admin/cron /ftpvideo video videoişlemci.php
- Yanlış dosyaveritabanında yol formatı - En yaygın veriler bug:
Dosya yolu MUST:
uploads/videos/original/{filename}Değil Sadece dosya adı ve Değil Ayrıca dahil de dahil olmak üzere de dahil de dahil olmak üzere de dahil de dahil de dahil olmak üzere de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil olmak üzere de de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil de dahil olmak üzere de dahil
ct/ Ad.- Yanlış dosya yollarını düzeltin:
- Temiz sıkı işlem kuyruğu:
- Dosyanın disk üzerinde var olduğunu belirtmek:
FFmpeg / FFprobe bulunamadı
Tanı:
Çözüm:
- FFmpeg yükleyin:
- yapılandırma gerçek yerlere giden yolları doğrulayın:
- PHP'nin kabuk komutlarını uygulayabilmesi için:
Video İşleme Hataları
Tanı:
- Kontrol işleme logları:
- Video kayıtlarını kontrol edin:
Ortak nedenler:
- Corrupted source file
- Desteksiz kodc
- Yetersiz disk alanı
- FFmpeg versiyonu çok eski (need 4.0+)
Çözüm: Alt yatan nedeni düzeltin, sonra yeniden işleme için videoyu sıfırlayın:
HLS Streaming çalışmıyor
.m3u8 Dosya yüklemez.Tanı:
- HLS dosyaları oluşturulsa kontrol edin:
- Verify the master playlist is accessible:
- Check MIME type configuration. Your web server must serve
.m3u8asapplication/vnd.apple.mpegurl:
Solution: Verify HLS files exist on CDN, MIME types are correct, and
securemedia.php token is valid.Thumbnails Not Generating
Diagnosis:
Common causes:
- ImageMagick not installed (
convertcommand needed for contact sheets) - FFmpeg failed during thumbnail extraction
- CDN upload for thumbnails failed (check storage server logs)
Solution:
CDN Upload Failures
Diagnosis:
- Check storage server configuration:
- Check file location records:
- Verify CDN credentials and connectivity from the admin panel.
File sharding formula:
floor(videoid / 1000) 1000Example: Video ID 4321 goes to shard 4000:
Solution: Check CDN credentials, test connectivity, verify storage server group assignment.
Distributed Conversion Server Issues
Diagnosis:
- Check server status:
- Check conversion logs:
- Verify settings:
Solution:
- Ensure
conversionuseremoteserversis set to1 - Verify remote server SSH/FTP connectivity
- Check that FFmpeg is installed on remote servers
- Verify
conversionfallbacktolocalis1for automatic fallback
API Issues
API Authentication Failures
Common causes:
- Wrong user ID column -
tblCMSUsersusesid, NOTuserid:
- Wrong status column -
tblCMSUsersusesaccountstatus, NOTstatus:
- JWT token expired - Tokens have an expiration time. Re-authenticate:
- JWT secret mismatch - Verify in config:
API Calls Failing from JavaScript
Diagnosis:
- Check
ApiClientbase URL:
- Check Network tab (F12) for the failing request - note the URL, status code, and response body.
- Verify the endpoint exists in the router:
- File:
ct/api/v1/index.php - 90+ endpoints defined
- File:
- Check JWT token:
Solution: Verify base URL detection, check endpoint exists in router, verify authentication token if endpoint requires auth.
API Returns Empty Data
{"success": true, "data": []} with no content.Diagnosis:
- Check if data exists in the database:
- Check feature toggles - some API endpoints return empty when features are disabled.
- Check query parameters - pagination offset may be beyond available data.
Solution: Verify data exists in the database and feature toggles are enabled.
CORS Errors
Access-Control-Allow-Origin errors.Cause: API and frontend on different domains or ports.
Solution: Ensure the API sets proper CORS headers:
Or in
.htaccess:Frontend Issues
Features Not Showing / All Disabled
Diagnosis:
- Test the features API endpoint:
- Check feature cache - APCu may have stale data:
- Check
featurehelper.php- all features default to enabled if not found in database.
- Verify feature settings in admin panel: Admin Panel -> Feature Toggles
Solution: Clear APCu cache, verify feature settings in admin panel, check that the API is reachable.
Translations Not Loading
videos.title instead of "Videos").Diagnosis:
- Verify
lang/en.jsonexists and is valid JSON:
- Check file permissions (must be readable by web server).
- Verify the translation key exists in the JSON:
- Check for typos in nested keys -
videos.sortby.videoidrequires all parent keys to exist.
Solution: Validate JSON syntax, check file permissions, verify key path exists in the translation file.
CSS Styles Not Applying
Rules:
- Only use
assets/css/style.css- no external CSS frameworks (Bootstrap, Tailwind, etc.) - Check for specificity conflicts with Style Manager overrides (Phase 12)
- Verify the stylesheet is loaded in
includes/header.php - Check browser cache - append
?v=timestampto stylesheet URL
Solution:
Dark Mode Not Working
Diagnosis:
- Check
featuredarkmodeis enabled in feature toggles - Verify
localStorageis available:
- Confirm
body.dark-modeCSS rules exist inassets/css/style.css - Check that both
bodyandhtmlelements get the class:
Solution: Enable the feature toggle, clear localStorage, verify CSS dark mode rules exist.
Video Player Not Loading
Diagnosis:
Check browser Network tab for
/ct/api/v1/videos/{id} requestVerify video data is returned with valid URLsCheck access control - user may lack permission (free/premium/VIP)For HLS: verify HLS.js is loaded and browser supports it
- Check
securemedia.phptoken generation:
Solution: Check API response, verify access control, ensure HLS.js or native HLS support is available, verify media token is valid.
Click Tracking Not Working
Critical rule: ALL external links MUST route through
click.php. Direct links incur a 100% skim penalty.Correct format:
Diagnosis:
- Check that
click.phpexists at the project root - Verify
tblClickTrackingis receiving records:
- Check
tblContentClicksfor aggregated counts
Solution: Audit all external links to ensure they use
click.php. Use browser DevTools to verify link href attributes.SEO Meta Tags Missing
Cause: SEO data must be loaded BEFORE
header.php is included.Correct order:
Diagnosis:
View page source and check for
<meta property="og:title"> tagsUse Facebook/Twitter debugger tools to validate Open Graph tags
- Check
ct/dat/seosettings.jsonfor template configuration
Solution: Ensure SEO data is loaded before header, verify
SeoHelper.php and InternalApiHelper.php are working.Cam Performers System
No Performers Appearing
Diagnosis (in order):
- Check cron jobs are running:
- Verify API credentials in Admin -> Cam Settings
- Check
tblCamsSitesfor enabled sites:
- Verify
featurelivecamsis enabled in feature toggles - Check logs:
- Test the internal API directly:
Solution: Enable cron jobs, verify API credentials, enable the feature toggle.
All Performers Showing Offline
Diagnosis:
- Run the cron update manually:
- Check if external API is responding:
- Verify API token hasn't expired
- Check database for online performers:
Solution: Run cron manually, verify external API credentials are valid.
External API 403 Forbidden
{"message": "Forbidden"} or HTML error page.Causes:
- Missing or invalid
x-api-keyheader - Missing
User-Agentheader (returns HTML error page) - API key revoked by CrakRevenue
Diagnosis:
Solution: Verify
x-api-key (stored in tblCamsSites.apiData) and ensure requests include a User-Agent header. Contact CrakRevenue if key was revoked.External API 401 Unauthorized
{"message": "Unauthorized: brands not allowed"} or similar.Causes:
- Invalid or missing
tokenparameter - Requesting brands not authorized for your token
- Token is domain-bound and being used from wrong domain
Diagnosis:
Solution: Verify
token (stored in tblCamsSites.parameters), ensure you only request authorized brands, verify token is for your domain.Slow Cam Performers Page
Diagnosis:
- Use the debug panel: add
?debug=1to the URL to see timing breakdown - Use the full debug tool:
Optimization checklist:
- Enable fast mode - ensure frontend uses
?fast=1parameter - Check APCu is installed and enabled:
- Verify stats cache cron is running:
- Reduce
perpageto 24 or less - Check for blocking database queries (see Table Locks)
Three-layer caching strategy:
- Layer 1: APCu in-memory cache (30s TTL)
- Layer 2: Database stats cache (
tblCamsPerformersStatsCache) - Layer 3: Fast mode (skip COUNT queries entirely)
Solution: Enable all three caching layers and verify cron jobs are running.
Affiliate Revenue Missing
Cause: External performer links not routed through
click.php.Required format:
Also verify:
- Affiliate ID is present in the
roomUrlfrom the external API tblClickTrackingis recording cam performer clicks- Performer
chatroomurlcontains valid affiliate tracking parameters
Solution: Audit all performer links to ensure
click.php routing. Verify affiliate ID in room URLs.Live Streaming (LiveKit)
LiveKit Server Not Starting
Diagnosis:
Common causes:
- Port conflicts (7880, 7881, 40000-40100 already in use)
- Invalid
livekit-config.yamlsyntax - Docker not installed or not running
- Insufficient permissions
Solution:
Stream Not Connecting
Diagnosis:
- Check LiveKit config in
ct/dat/config.inc.php:
- Verify WebSocket connection from browser:
- Open browser console (F12)
- Look for WebSocket connection errors
- Check if
wss://URL is accessible
- Verify firewall rules:
Required ports:
7880- WebSocket signaling7881- TCP media40000-40100- UDP media (WebRTC)
Solution: Verify LiveKit credentials match between config and server, check firewall ports, ensure SSL is configured for
wss://.High Latency / Buffering
Causes:
- UDP ports blocked - WebRTC falls back to TCP (higher latency)
- Server overloaded
- Client bandwidth insufficient
Solution:
- Ensure UDP ports 40000-40100 are open
- Check server load:
- Verify
nodeipinlivekit-config.yamlmatches your public IP
Chat Not Working
Diagnosis:
- Check
tblLiveStreamChatfor recent messages:
- Verify WebSocket connection in browser console
- Check that the stream ID is valid in
tblLiveStreams
Solution: Verify stream exists, WebSocket is connected, and chat API endpoint is responding.
Creator Monetization
Tips Not Processing
Diagnosis:
Common causes:
- Insufficient token balance
- Creator profile not verified
- API endpoint error (check response)
Solution: Verify sender has sufficient tokens, creator profile is active, and
POST /tips/send returns success.Earnings Not Aggregating
Cause: Earnings aggregation cron job not running.
Required cron:
Diagnosis:
Solution: Ensure the
aggregatecreatorearnings.php cron job is running every minute.Creator Posts Not Displaying
Diagnosis:
- Check
featurecreatorpostsis enabled - Verify posts exist:
- Check post visibility settings (public vs subscriber-only vs PPV)
- Verify media uploads if post contains images/video:
Solution: Enable the feature toggle, verify posts exist in the database, check access control for post visibility.
Subscription Issues
Diagnosis:
Solution: Verify
featuresubscriptions is enabled, check payment processing, verify subscription record status.Authentication & Users
Login Fails
Diagnosis:
- Test the auth API directly:
- Check user account status:
Remember: column is
accountstatus, NOT status.- Check if account is locked, suspended, or unverified.
Solution: Verify account exists, is active (
accountstatus = 'active'), and email is verified if required.Admin Locked Out (Too Many Failed Attempts)
Cause: The rate limiter blocks the IP address after 5 failed login attempts for 15 minutes. If you also forgot your password, you'll need to reset both the lockout and the password.
Solution:
Step 1: Clear the rate limit lockout
Run this SQL in phpMyAdmin or MySQL CLI:
This immediately removes all login blocks for all IPs.
Step 2 (if needed): Reset the admin password
If you also forgot your password, you have two options:
Option A: Use the built-in repair tool
Navigate to
ct/admin/repair.php?action=setupBasicAuth and set a new password. This page does not require login.repair.php via .htaccess or server configuration.Option B: Reset directly via SQL
- Generate a new password hash. Create a temporary PHP file on your server (e.g.,
hash.php):
- Visit the file in your browser and copy the hash output.
- Run this SQL:
- Delete
hash.phpimmediately after use.
Step 3: Verify and log in
Go to
ct/admin/ctlogin.php and log in with your new password.Prevention:
- Store your admin password in a password manager.
- The lockout expires automatically after 15 minutes if you prefer to wait.
Session Issues
Diagnosis:
- Check
auth/setsession.phpis being called after login - Verify session cookie is being set:
- Check PHP session configuration:
Solution: Ensure
setsession.php is called after API login returns JWT token. Verify session cookie domain matches.2FA Problems
Diagnosis:
- Check
feature2fais enabled - Verify server time is accurate (TOTP codes are time-based):
- Time drift of >30 seconds will cause code rejection.
Solution: Sync server time with NTP, verify 2FA secret is stored correctly.
Cron Jobs
Verifying Cron Jobs Are Running
Check if they've run recently:
Test a cron job manually:
Required Cron Schedule
- php /path/to/ct/admin/cron/ftpvideoprocessor.php
- php /path/to/ct/admin/cron/aggregatecreatorearnings.php
Impact of missing cron jobs:
Cron Tasks Failing with Exit Code 1 (exec Functions Disabled)
Symptom:
Or:
Tasks fail when launched by sitecron.php but work fine when run manually via SSH (php apicron.php).
Cause:
PHP-FPM has exec, shellexec, procopen, and related functions disabled in disablefunctions. The sitecron.php scheduler needs these to spawn subtasks. The CLI PHP config usually has them enabled, which is why running manually works.
Fix:
- Open your PHP-FPM config:
- Find the
disablefunctionsline. It will look something like:
- Remove
exec,system,passthru,shellexec,procopen,popenfrom the list. Keep thepcntlfunctions disabled. The line should look like:
- Restart PHP-FPM:
- Verify:
Why these functions are needed:
exec,shellexec,procopen- Required bysitecron.phpto spawn cron subtaskssystem,passthru- Used by video processing (FFmpeg/FFprobe)popen- Used by some processing pipelines
The pcntl functions should remain disabled as they are for process forking and are not needed by ComusThumbz.
Debug Tools Reference
?key=comus2025Kill a blocking query via URL:
Cam performers debug panel:
Shows: API URL, TTFB, download time, JSON parse time, DOM render time.
Log File Locations
Common SQL Fixes