Troubleshooting

Running into problems? This guide covers the most common issues and how to fix them. If you can't find your issue here, check the Error Messages page or contact support.

Server Issues

Server shows as Offline

Your server appears offline when the TurboV agent cannot communicate with the backend.

Check the following:

Is the server running? SSH into your server and verify it's responsive
Is the agent service running?
```
systemctl status turbov-agent
```

Can the server reach the backend?

curl -I https://your-backend-url.com/health

Check agent logs for errors:
```
journalctl -u turbov-agent -n 100
```

Agent won't start

If the agent service fails to start, check these common causes:

Missing configuration: Ensure SERVER_URL and REGISTRATION_TOKEN are set
Docker not installed: The agent requires Docker to run containers
Permission issues: The agent user needs Docker access
Port conflicts: Ensure no other service is using required ports

High CPU or memory usage

If your server is running hot:

Check which containers are using resources:
```
docker stats
```
Review application logs for errors or infinite loops
Consider adding resource limits to containers
Scale to a larger server if consistently high

Deployment Issues

Deployment stuck in 'Building' state

Deployments usually take 1-5 minutes. If stuck longer:

Check deployment logs for errors
Verify the repository is accessible
Ensure Docker has enough disk space:
```
df -h
```
Check if Docker build is running:
```
docker ps
```

Build fails with 'Dockerfile not found'

TurboV couldn't find or generate a Dockerfile:

Add a Dockerfile to your repository root
Or enable auto-detection in environment settings
Verify the Dockerfile is named exactly "Dockerfile"

GitHub repository not accessible

If TurboV can't access your repository:

Verify the GitHub App is installed on the repository
Check if the repository is private and requires authorization
Ensure the branch name is correct
Try reconnecting your GitHub account in Settings

npm install fails during build

Common causes for npm/pnpm/yarn failures:

Private npm packages without authentication
Outdated lock files
Memory limits during install
Network timeouts

Solutions:

Add .npmrc with authentication tokens
Delete lock file and retry
Increase build memory
Use a network mirror

Application Issues

Application won't start

If your container starts but the app doesn't:

Check application logs in the dashboard
Verify all environment variables are set
Ensure the app listens on 0.0.0.0, not just localhost
Check for missing files or dependencies

Application crashes after starting

Common causes:

Missing environment variables
Database connection failures
Unhandled exceptions
Memory limits

Debug steps:

Review runtime logs
Check environment variable configuration
Verify database connectivity
Monitor resource usage

Can't access application URL

If your app is running but not accessible:

Verify the domain is configured correctly
Check DNS records point to your server
Ensure SSL certificate is provisioned
Verify the application port matches configuration

Domain & SSL Issues

Domain not resolving

Verify DNS A/CNAME records are correct
Wait for DNS propagation (up to 48 hours)
Check for typos in the domain name
Use a DNS checker like dnschecker.org

SSL certificate stuck in 'Pending'

Ensure DNS is properly configured first
Verify port 80 is accessible (required for Let's Encrypt)
Check firewall rules
Try removing and re-adding the domain

SSL certificate failed

Verify DNS records point to the correct server
Check for CAA records that might block Let's Encrypt
Ensure no other service is using port 80
Review Traefik logs for errors

Getting Help

If you can't resolve your issue:

Check the Error Messages page for specific error codes
Review the FAQ for common questions
Contact support with:
- Error messages
- Relevant logs
- Steps to reproduce