Troubleshooting

This guide covers common issues you may encounter when setting up or running Octeth, along with their solutions.

Installation Issues

Installation Fails with "License Invalid" Error

Problem: The installer rejects your license key

Solutions:

Verify the license file is correctly formatted:
bash
```
cat /opt/octeth/data/license.dat
```
Ensure there are no extra spaces or line breaks
Download a fresh license file from Octeth Client Area
Check that your license is active and not expired
Contact support if the issue persists

Docker Services Won't Start

Problem: Docker containers fail to start during installation

Check Docker Status:

bash

systemctl status docker
docker ps -a

Solutions:

Restart Docker service:
bash
```
systemctl restart docker
```
Check for port conflicts (especially ports 80, 443, 3306, 6379):
bash
```
netstat -tulpn | grep -E ':(80|443|3306|6379)\s'
```
Ensure sufficient disk space:
bash
```
df -h
```
Review Docker logs:
bash
```
journalctl -u docker -n 100
```

Database Connection Errors

Problem: Cannot connect to MySQL database

Check Database Status:

bash

/opt/octeth/cli/octeth.sh docker:status

Solutions:

Verify MySQL container is running:
bash
```
docker ps | grep mysql
```
Check MySQL credentials in environment file:
bash
```
cat /opt/octeth/.oempro_env | grep MYSQL
```
Restart MySQL container:
bash
```
docker restart oempro_mysql
```
Check MySQL logs:
bash
```
docker logs oempro_mysql
```

Performance Issues

Slow Email Delivery

Problem: Campaigns take too long to send

Diagnose:

bash

/opt/octeth/cli/octeth.sh sendengine:status
/opt/octeth/cli/octeth.sh backend:status

Solutions:

Scale up send engine instances:

bash

/opt/octeth/cli/octeth.sh sendengine:scale 5

Check SMTP server response times

Verify send engine logs for errors:

bash

/opt/octeth/cli/octeth.sh sendengine:logs

Review RabbitMQ queue depth:

bash

docker exec oempro_rmq rabbitmqctl list_queues

High Memory Usage

Problem: Server running out of memory

Check Memory Usage:

bash

free -h
docker stats

Solutions:

Adjust MySQL configuration to use less memory:

bash

/opt/octeth/cli/octeth.sh mysql:switch-config standard

Reduce RabbitMQ memory limit if needed:

bash

vi /opt/octeth/.oempro_rabbitmq_env
# Adjust RABBITMQ_VM_MEMORY_HIGH_WATERMARK

Restart services to clear memory:

bash

/opt/octeth/cli/octeth.sh docker:restart

Consider upgrading server RAM

Disk Space Full

Problem: Server has no remaining disk space

Check Disk Usage:

bash

df -h
du -sh /opt/octeth/* | sort -h
du -sh /var/lib/docker/* | sort -h

Solutions:

Clear old Docker images:
bash
```
docker system prune -a
```
Clear log files:
bash
```
/opt/octeth/cli/octeth.sh logs:reset
```

Remove old backups if using backup addon:

bash

rm -rf /var/backups/octeth/daily/backup-older-than-30-days*

Expand disk space on your server

Email Delivery Issues

Emails Going to Spam

Problem: Emails consistently land in spam folders

Verify DNS Configuration:

bash

dig TXT yourdomain.com +short  # SPF
dig TXT octeth._domainkey.yourdomain.com +short  # DKIM
dig TXT _dmarc.yourdomain.com +short  # DMARC

Solutions:

Review Sender Domain DNS Settings guide
Verify SPF, DKIM, and DMARC records are correctly configured
Check domain reputation using SenderScore
Warm up new IP addresses gradually
Review email content for spam trigger words
Ensure proper list hygiene (remove bounces and complaints)

Bounces and Rejections

Problem: High bounce rate or emails being rejected

Check Bounce Logs:

Log in to Octeth Admin Dashboard
Navigate to Reports > Bounce Reports
Review rejection reasons

Common Solutions:

Invalid Recipients: Clean your email list, remove invalid addresses
Blacklisted IP: Check if your IP is on blacklists using MXToolbox
Authentication Failures: Verify DNS records (SPF, DKIM, DMARC)
Content Filters: Review email content, remove spam triggers
Rate Limiting: Slow down sending rate for specific domains

SMTP Connection Failures

Problem: Cannot connect to SMTP servers

Test SMTP Connection:

bash

telnet smtp.example.com 587
# Or for SSL/TLS
openssl s_client -connect smtp.example.com:465

Solutions:

Verify SMTP credentials in Octeth delivery server settings
Check firewall isn't blocking SMTP ports (25, 465, 587)
Confirm SMTP server is reachable from your Octeth server
Review SMTP server logs for authentication errors
Try alternative SMTP port (587 vs 465)

Backend Process Issues

Backend Workers Not Running

Problem: Email campaigns not processing

Check Status:

bash

/opt/octeth/cli/octeth.sh backend:status

Solutions:

Restart backend processes:

bash

/opt/octeth/cli/octeth.sh backend:restart

Check supervisor status:

bash

docker exec oempro_app supervisorctl status

Review error logs:
bash
```
/opt/octeth/cli/octeth.sh logs:tail
```
Verify RabbitMQ is running:
bash
```
docker ps | grep rabbitmq
```

Cron Jobs Not Executing

Problem: Scheduled tasks aren't running

Check Cron Status:

bash

docker exec oempro_app crontab -l
docker exec oempro_app supervisorctl status cron

Solutions:

Restart cron service:

bash

docker exec oempro_app supervisorctl restart cron

Check cron logs:

bash

docker exec oempro_app tail -f /var/log/cron.log

Verify system time is correct:
bash
```
date
```

Database Issues

Database Corruption

Problem: MySQL reports corrupted tables

Check and Repair:

bash

docker exec oempro_mysql mysqlcheck -u root -p oempro --auto-repair

Solutions:

Stop Octeth:
bash
```
/opt/octeth/cli/octeth.sh backend:stop
```

Repair tables:

bash

docker exec oempro_mysql mysqlcheck -u root -p oempro --repair --extended

If repair fails, restore from backup
Restart Octeth:
bash
```
/opt/octeth/cli/octeth.sh backend:start
```

Slow Queries

Problem: Database queries taking too long

Enable Slow Query Log:

bash

docker exec oempro_mysql mysql -u root -p -e "SET GLOBAL slow_query_log = 'ON';"
docker exec oempro_mysql mysql -u root -p -e "SET GLOBAL long_query_time = 2;"

Solutions:

Review slow query log:

bash

docker exec oempro_mysql cat /var/lib/mysql/slow-query.log

Optimize tables:

bash

docker exec oempro_mysql mysqlcheck -u root -p oempro --optimize

Consider upgrading to MySQL highperf configuration:

bash

/opt/octeth/cli/octeth.sh mysql:switch-config highperf

Web Interface Issues

Cannot Access Admin Dashboard

Problem: Admin login page not loading

Check Web Server:

bash

curl -I http://203.0.113.10/app/admin/

Solutions:

Verify Docker containers are running:
bash
```
/opt/octeth/cli/octeth.sh docker:status
```

Check HAProxy status:

bash

docker ps | grep haproxy
docker logs oempro_haproxy

Verify firewall isn't blocking port 80/443:
bash
```
ufw status
```

Restart all containers:

bash

/opt/octeth/cli/octeth.sh docker:restart

Problem: Cannot log in with correct credentials

Reset Admin Password:

bash

docker exec oempro_app php /var/www/html/cli/reset-admin-password.php

Solutions:

Clear browser cache and cookies
Try different browser or incognito mode
Check session storage (Redis):
bash
```
docker exec oempro_redis redis-cli ping
```

Regenerate authentication tokens:

bash

/opt/octeth/cli/octeth.sh regenerate-auth-tokens

System Health Checks

Running Health Check

Verify all services are operational:

bash

/opt/octeth/cli/octeth.sh health:check

This comprehensive check validates:

MySQL connection
Redis connectivity
RabbitMQ status
ClickHouse database
ElasticSearch service
All backend processes
File permissions
Container health

Viewing System Logs

Real-time Error Logs:

bash

/opt/octeth/cli/octeth.sh logs:tail

Docker Container Logs:

bash

docker logs oempro_app
docker logs oempro_mysql
docker logs oempro_redis
docker logs oempro_rmq

Getting Help

If you've tried the solutions above and still need assistance:

Gather Information:
- Run health check: /opt/octeth/cli/octeth.sh health:check
- Create log snapshot: /opt/octeth/cli/octeth.sh logs:snapshot
- Note exact error messages
- Document steps to reproduce
Contact Support:
- Email: support@octeth.com
- Include your Octeth version
- Attach log snapshots
- Describe what you've already tried

Pro Tip

Enable debug mode temporarily when troubleshooting:

bash

vi /opt/octeth/.oempro_env
# Set OEMPRO_DEBUG=true
# Set OEMPRO_LOG_LEVEL=DEBUG
/opt/octeth/cli/octeth.sh docker:restart

Remember to disable debug mode after troubleshooting to avoid performance impact.

Troubleshooting ​

Installation Issues ​

Installation Fails with "License Invalid" Error ​

Docker Services Won't Start ​

Database Connection Errors ​

Performance Issues ​

Slow Email Delivery ​

High Memory Usage ​

Disk Space Full ​

Email Delivery Issues ​

Emails Going to Spam ​

Bounces and Rejections ​

SMTP Connection Failures ​

Backend Process Issues ​

Backend Workers Not Running ​

Cron Jobs Not Executing ​

Database Issues ​

Database Corruption ​

Slow Queries ​

Web Interface Issues ​

Cannot Access Admin Dashboard ​

Login Failures ​

System Health Checks ​

Running Health Check ​

Viewing System Logs ​

Getting Help ​

Troubleshooting

Installation Issues

Installation Fails with "License Invalid" Error

Docker Services Won't Start

Database Connection Errors

Performance Issues

Slow Email Delivery

High Memory Usage

Disk Space Full

Email Delivery Issues

Emails Going to Spam

Bounces and Rejections

SMTP Connection Failures

Backend Process Issues

Backend Workers Not Running

Cron Jobs Not Executing

Database Issues

Database Corruption

Slow Queries

Web Interface Issues

Cannot Access Admin Dashboard

Login Failures

System Health Checks

Running Health Check

Viewing System Logs

Getting Help