Troubleshooting

This guide covers common issues with self-hosted ZəkaHouse instances and how to resolve them.

First Step: Run Diagnostics

Before diving into specific issues, run the built-in diagnostics:

zeka-learnhouse doctor

This checks Docker availability, container health, port conflicts, DNS resolution, and disk space. It will often identify the root cause of problems automatically.

Services Not Starting

Symptoms: zeka-learnhouse start fails, or containers are stopped or restarting.

Common causes:

Docker is not running. Verify Docker is running with docker info. Start the Docker daemon if needed.
Insufficient memory. ZəkaHouse requires at least 2 GB of RAM. Check available memory with free -m (Linux) or Activity Monitor (macOS).
Port conflicts. Another service may be using port 80 or 443. Check with lsof -i :80 and stop the conflicting service. zeka-learnhouse doctor will also detect port conflicts.
Corrupted configuration. Re-run zeka-learnhouse setup to regenerate configuration files.

Database Connection Errors

Symptoms: Application logs show database connection errors, or the app fails to start with PostgreSQL-related messages.

Steps to resolve:

Run diagnostics to check container health:
```
zeka-learnhouse doctor
```
Check database logs:
```
zeka-learnhouse logs
```
Look for log lines from the db container.
Verify the connection string in your .env file matches the database container’s configuration.
If the database container keeps restarting, it may be running out of disk space. Check available disk space on the host.

Port Conflicts

Symptoms: Error messages about ports already being in use.

Check which process is using the port:

# Check port 80
lsof -i :80
 
# Check port 443
lsof -i :443

Stop the conflicting service, or reconfigure ZəkaHouse to use a different port by re-running zeka-learnhouse setup.

Storage Permission Errors

Symptoms: File upload fails, or logs show permission denied errors when writing to storage.

For filesystem storage:

Docker volumes should handle permissions automatically. If issues persist, check that the Docker daemon has appropriate permissions on the host filesystem.

For S3 storage:

Verify your S3 credentials have read and write permissions on the configured bucket.
Check that the bucket name (LEARNHOUSE_S3_API_BUCKET_NAME) and endpoint URL (LEARNHOUSE_S3_API_ENDPOINT_URL) are correct in your .env file.
Test connectivity to the S3 endpoint from the server.

Authentication Issues

Symptoms: Users cannot log in, or sessions expire immediately.

Verify NEXTAUTH_SECRET is set and has not changed since the last restart. Changing the secret invalidates all existing sessions.
Verify LEARNHOUSE_COOKIE_DOMAIN matches your actual domain. Incorrect cookie domain prevents authentication from working.
If using SSL, ensure NEXTAUTH_URL uses https://.

Performance Issues

Symptoms: Slow page loads, timeouts, or high resource usage.

Run diagnostics:
```
zeka-learnhouse doctor
```
Review application logs for errors or slow operations:
```
zeka-learnhouse logs
```
Check resource limits on your containers:
```
zeka-learnhouse deployments
```
Consider increasing server resources (RAM, CPU) if usage is consistently high.
If using filesystem storage with a large amount of content, consider migrating to S3-compatible storage.

Resetting Your Instance

Resetting your instance deletes all data. Create a backup first if you want to preserve any data.

If you need to start fresh:

# Back up current data (optional)
zeka-learnhouse backup
 
# Stop all services
zeka-learnhouse stop
 
# Re-run setup
zeka-learnhouse setup
 
# Start fresh
zeka-learnhouse start

Getting Help

If you cannot resolve an issue using this guide:

Run zeka-learnhouse doctor and include the output in your report.
Reach out to your ZekaLab contact with the diagnostic output, relevant log output, and your environment (OS, Docker version, RAM).

PreviousMonitoring NextUpdates