Troubleshooting

Troubleshooting

Common issues and solutions for NNTmux.

Installation Issues

Composer Install Fails

Error: Your requirements could not be resolved to an installable set of packages

Solution:

# Update composer
composer self-update

# Clear cache and retry
composer clear-cache
composer install --no-cache

PHP Extension Missing

Error: ext-xxx is missing from your system

Solution:

# Install common extensions
sudo apt install php8.3-{curl,mbstring,xml,zip,gd,intl,pcntl,mysql}

# Verify
php -m | grep -i extension_name

Permission Denied

Error: Permission denied or failed to open stream

Solution:

# Fix ownership
sudo chown -R www-data:www-data /var/www/nntmux

# Fix permissions
sudo chmod -R 755 /var/www/nntmux
sudo chmod -R 775 storage bootstrap/cache

# Fix SELinux (if applicable)
sudo chcon -R -t httpd_sys_rw_content_t storage bootstrap/cache

Processing Issues

Releases Not Being Created

Symptoms: Headers downloaded but no releases appearing

Check:

1. Active groups:

   php artisan tinker
   >>> DB::table('usenet_groups')->where('active', 1)->count();

2. Headers exist:

   SELECT COUNT(*) FROM binaries;
   SELECT COUNT(*) FROM parts;

3. Processing is running:

   ps aux | grep "php artisan"

4. Check logs:

   tail -f storage/logs/laravel.log

Solutions:

• Ensure groups are active in admin panel
• Run release processing manually: php artisan nntmux:releases
• Check NNTP connection: php artisan nntmux:test-nntp

Post-Processing Stuck

Symptoms: Releases exist but no metadata (covers, NFOs, etc.)

Check:

1. Queue is running:

   php artisan queue:work --status

2. Jobs in queue:

   SELECT COUNT(*) FROM jobs;
   SELECT COUNT(*) FROM failed_jobs;

Solutions:

# Process failed jobs
php artisan queue:retry all

# Clear stuck jobs
php artisan queue:flush

# Run post-processing manually
php artisan nntmux:postprocess

NNTP Connection Failed

Error: Unable to connect to NNTP server

Check:

1. Credentials in .env:

   grep NNTP .env

2. Network connectivity:

   telnet news.provider.com 563
   openssl s_client -connect news.provider.com:563

3. Test connection:

   php artisan nntmux:test-nntp

Solutions:

• Verify username/password
• Try different port (119 vs 563)
• Check SSL settings
• Contact Usenet provider

Database Issues

Connection Refused

Error: SQLSTATE[HY000] [2002] Connection refused

Check:

# Is MariaDB running?
sudo systemctl status mariadb

# Can you connect manually?
mysql -u nntmux -p

Solutions:

# Start MariaDB
sudo systemctl start mariadb

# Check socket path
mysql -u root -p -S /var/run/mysqld/mysqld.sock

Lock Wait Timeout

Error: Lock wait timeout exceeded

Check:

SHOW FULL PROCESSLIST;
SHOW ENGINE INNODB STATUS\G

Solutions:

# Increase timeout in my.cnf
innodb_lock_wait_timeout = 120

# Kill blocking query
mysql -e "KILL process_id"

Disk Space Full

Symptoms: Queries fail, server unresponsive

Check:

df -h
du -sh /var/lib/mysql/*

Find large tables:

SELECT 
    table_name,
    ROUND((data_length + index_length) / 1024 / 1024, 2) AS 'Size (MB)'
FROM information_schema.tables
WHERE table_schema = 'nntmux'
ORDER BY (data_length + index_length) DESC
LIMIT 10;

Solutions:

# Clean Laravel Pulse data
php artisan pulse:purge

# Clean old releases
php artisan nntmux:cleanup --days=180

# Clean binary data
php artisan nntmux:cleanup-binaries

# Optimize tables (reclaim space)
php artisan nntmux:optimize-tables

Laravel Pulse Disk Usage

Check:

SELECT 
    table_name,
    ROUND(data_length/1024/1024, 2) as 'Size (MB)'
FROM information_schema.tables
WHERE table_schema = 'nntmux' 
AND table_name LIKE 'pulse%';

Solution:

php artisan pulse:purge

# Or disable Pulse in .env
PULSE_ENABLED=false

Web Interface Issues

500 Internal Server Error

Check:

# Application logs
tail -100 storage/logs/laravel.log

# Web server logs
tail -100 /var/log/nginx/error.log
tail -100 /var/log/apache2/error.log

# PHP-FPM logs
tail -100 /var/log/php8.3-fpm.log

Common causes:

• Missing .env file
• Invalid APP_KEY
• Database connection failed
• Permission issues

Solutions:

# Regenerate key
php artisan key:generate

# Clear all caches
php artisan cache:clear
php artisan config:clear
php artisan view:clear
php artisan route:clear

# Fix permissions
chmod -R 775 storage bootstrap/cache

502 Bad Gateway

Cause: PHP-FPM not running or timed out

Check:

sudo systemctl status php8.3-fpm

Solutions:

# Restart PHP-FPM
sudo systemctl restart php8.3-fpm

# Increase timeout in nginx
location ~ \.php$ {
    fastcgi_read_timeout 300;
}

Slow Page Loads

Check:

1. Enable slow query log:

   SET GLOBAL slow_query_log = 'ON';
   SET GLOBAL long_query_time = 1;

2. Monitor queries:

   SHOW PROCESSLIST;

3. Check PHP-FPM:

   # Enable slow log in php-fpm pool
   slowlog = /var/log/php-fpm/slow.log
   request_slowlog_timeout = 5s

Solutions:

• Tune database (see Database Tuning)
• Add missing indexes
• Enable query caching
• Use search engine for full-text search

CSS/JS Not Loading

Check:

ls -la public/build/

Solutions:

# Rebuild assets
npm install
npm run build

# Check permissions
chmod -R 755 public/build

Search Issues

Search Returns No Results

Check:

1. Search engine running:

   # ManticoreSearch
   mysql -h 127.0.0.1 -P 9306 -e "SHOW STATUS"
   
   # Elasticsearch
   curl localhost:9200

2. Index has data:

   # ManticoreSearch
   mysql -h 127.0.0.1 -P 9306 -e "SELECT COUNT(*) FROM releases"

Solutions:

# Rebuild index
php artisan nntmux:index-manticore --fresh

Search Engine Connection Failed

Check:

# ManticoreSearch
ss -tlnp | grep 9308
sudo systemctl status manticore

# Elasticsearch
ss -tlnp | grep 9200
sudo systemctl status elasticsearch

Solutions:

# Restart service
sudo systemctl restart manticore
# or
sudo systemctl restart elasticsearch

TV/Movie Matching Issues

Releases Not Matching

Check:

1. API keys valid:

   php artisan nntmux:test-apis

2. Show exists in database:

   SELECT * FROM videos WHERE title LIKE '%Show Name%';

Solutions:

# Reprocess unmatched releases
php artisan nntmux:reprocess-tv

# Refresh episodes for show
php artisan tv:refresh-episodes --video-id=12345

Missing Episodes

See TV & Movie Processing guide.

Permission Issues

File Ownership Problems

Symptoms: Can't write to storage, uploads fail, processing errors

Diagnosis:

# Check who owns files
ls -la storage/
ls -la bootstrap/cache/

# Check web server user
ps aux | grep nginx
ps aux | grep php-fpm

Solution:

# Set correct ownership
sudo chown -R www-data:www-data storage bootstrap/cache

# If running tmux as different user
sudo chown -R youruser:www-data storage
sudo chmod -R 775 storage

Tmux Running as Root

Symptoms: Files created with root ownership

Check:

ps aux | grep tmux

Solution:

# Kill root tmux session
sudo tmux kill-server

# Start as correct user
su - youruser -c "cd /var/www/nntmux && php artisan tmux:start"

Log Locations

Log	Location
Application	storage/logs/laravel.log
Tmux	misc/update/tmux/logs/
nginx	/var/log/nginx/
Apache	/var/log/apache2/
PHP-FPM	/var/log/php8.3-fpm.log
MariaDB	/var/log/mysql/
ManticoreSearch	/var/log/manticore/
Elasticsearch	/var/log/elasticsearch/

Getting Help

If you can't resolve an issue:

1. Search existing issues: GitHub Issues
2. Check discussions: GitHub Discussions
3. Join Discord: Discord Server

When reporting issues, include:

• NNTmux version (php artisan --version)
• PHP version (php -v)
• Database version (mysql --version)
• Relevant log entries
• Steps to reproduce