Troubleshooting

Common issues and solutions for working with Tun.

Daemon Not Connecting

If the Tun App cannot connect to the Tun Engine daemon:

• Verify daemon is running: curl http://127.0.0.1:4343/v1/sites
• Check firewall settings
• Verify port 4343 is not in use
• Restart the Tun Engine daemon if needed

Site Won't Start

If a site fails to start, check the following:

• Ensure the container backend (OrbStack, Colima, Podman, or Docker Engine) is running
• Check that containers are healthy (view container status)
• Verify PHP version is correctly configured
• Review the Errors tab for specific error messages
• Check container logs for detailed error information

Container Backend Issues

If you're experiencing issues with container backends:

• OrbStack: Ensure OrbStack is running and accessible
• Colima: Verify Colima is started with colima start
• Podman: Check Podman service is running
• Docker Engine: Ensure Docker daemon is running

Tun will automatically detect which backend is available. If switching backends, restart the Tun Engine daemon.

Database Connection Errors

If you're unable to connect to the database:

• Verify MySQL is running (check the Database tab)
• Confirm database credentials in the Overview tab
• Try re-initialising the site's database
• Check Craft's config/db.php file

Hostname Mode Not Resolving

If your hostname (e.g., mysite.tun.test) isn't working:

1. Verify the domain is added to /etc/hosts file:

   127.0.0.1 mysite.tun.test

2. Flush your DNS cache:
   • macOS: sudo dscacheutil -flushcache
   • Linux: sudo systemd-resolve --flush-caches
   • Windows: ipconfig /flushdns
3. Restart your browser
4. Verify the reverse proxy is running and routing correctly
5. Try switching to localhost mode temporarily to test

SSL Certificate Issues

If HTTPS isn't working with custom domains:

• Ensure you're using custom domain routing (not localhost)
• Check that the certificate was generated (look for certificate files)
• Try regenerating the certificate in site settings
• Clear your browser's SSL state

PHP Errors

Common PHP-related issues:

• Version mismatch: Ensure your site's PHP version matches Craft's requirements
• Extensions missing: Tun includes all required PHP extensions, but verify in PHP settings
• Memory limits: Increase PHP memory limit if needed in site configuration

Craft CLI Commands Not Working

If Craft CLI commands fail:

• Ensure the site is started (containers must be running)
• Verify Craft CMS is properly installed in the project path
• Check that the container can access the project files
• Review command output in the Tools tab for specific errors

Commands are executed using docker compose exec (or equivalent for your container backend) in the site's container.

Re-initialising a Site

If a site needs to be re-initialised:

1. Stop the site if it's running
2. Use the Craft CLI integration to re-run installation: tun craft [id] -- install
3. Or manually run composer create-project craftcms/craft . in the project path
4. Restart the site

Note: The tun sites init command can also be used to initialise or re-initialise a Craft CMS project.

Viewing Logs

Tun provides several ways to view logs:

• Site Logs: View site logs directly in the application from the Tools tab
• Real-time Updates: Logs update in real-time as events occur
• Craft CMS Logs: Access logs in storage/logs/ via the site folder
• Container Logs: View container logs through your container backend's interface

Getting Help

If you're still experiencing issues:

• Check the Errors tab in Tun for centralised error tracking
• Review detailed error information and stack traces
• Check Craft CMS logs in storage/logs/
• Verify container backend is functioning correctly
• Review the Tun Engine daemon logs
• Contact support with error details, system information, and container backend type