ServBay Web Server Troubleshooting Guide

ServBay supports Caddy, NGINX, and Apache as the default web servers, providing you with a flexible local development environment. During usage, you may encounter issues such as inaccessible websites, slow loading, or errors like 500 Internal Server Error. This guide is designed to help you diagnose and resolve common web server issues within the ServBay environment.

Using ServBay's Built-In Troubleshooting Tool

ServBay offers a powerful troubleshooting tool that can automatically detect and flag common configuration and service issues. We strongly recommend running this tool as your first step whenever you encounter a problem.

Open the ServBay app and click Troubleshooting in the left sidebar to access ServBay's built-in diagnostics interface.

This tool checks the status of ServBay's core components, port usage, configuration file syntax, and more. It provides real-time prompts and suggestions to help you quickly pinpoint the root cause of problems.

Checking Web Server Configuration Files

Errors in web server configuration files are a common cause of website inaccessibility. ServBay provides dedicated syntax checking tools for each supported web server.

Checking Caddyfile

Use Caddy's built-in validate command to verify that your Caddyfile configuration is correct.

/Applications/ServBay/bin/caddy validate -c /Applications/ServBay/etc/caddy/Caddyfile

If the syntax is correct, the command will return Valid configuration. If there are errors, you’ll receive prompts based on the error type.

Note: The caddy validate command may output many INFO or WARN messages; these are typically from Caddy’s internal load process and are not necessarily errors. As long as you get Valid configuration in the end, the syntax is correct.

Common Caddyfile Error Examples

• Certificate file not found:

  2024/12/09 17:24:16.970 INFO using config from file {"file": "/Applications/ServBay/etc/caddy/Caddyfile"}
  ... (other INFO/WARN messages) ...
  Error: loading http app module: provision http: getting tls app: loading tls app module: provision tls: loading certificates: open /Applications/ServBay/ssl/private/tls-certs/mail.servbay.host/mail.servbay.host.1crt: no such file or directory

  If you see errors like loading certificates: open xxxxx: no such file or directory, this means the SSL certificate file path specified in your Caddyfile is incorrect or the file does not exist. Double-check that the certificate (.crt/.cer/.pem) and private key (.key) paths in your site configuration are correct, and that the files actually exist at those paths. ServBay supports manual import and ACME auto-generation of SSL certificates—please verify your ServBay SSL settings accordingly.

• Incorrect root directory path (contains spaces):

  2024/12/09 17:26:37.371 INFO using config from file {"file": "/Applications/ServBay/etc/caddy/Caddyfile"}
  Error: adapting config using caddyfile: parsing caddyfile tokens for 'root': too many arguments; should only be a matcher and a path, at /Applications/ServBay/etc/caddy/Caddyfile:1388

  The error parsing caddyfile tokens for 'root': too many arguments is typically caused by a space in the root directory path. For example, in root * /Applications/ServBay/www/public web, public web would be treated as two separate arguments. The correct way is to enclose paths containing spaces within double quotes: root * "/Applications/ServBay/www/public web".

  Suggestion: To avoid such issues, it's highly recommended to refrain from using spaces or special characters in file and directory names. You can use hyphens - or underscores _ for separation, such as public-folder or public_dir.

• Rewrite rule errors:

  If invalid rewrite rules (for example, rules copied directly from NGINX) are used in the Caddyfile, syntax checking will fail. Refer to the Caddy Rewrite module documentation or ServBay's own Migration Guide from NGINX to ServBay to ensure your rules are correctly formatted.

NGINX Configuration Check

Use NGINX's built-in -t option to test the configuration file's syntax and validity.

/Applications/ServBay/bin/nginx -t

If everything is correct, the command will output:

nginx: the configuration file /Applications/ServBay/etc/nginx/nginx.conf syntax is ok
nginx: configuration file /Applications/ServBay/etc/nginx/nginx.conf test is successful

If errors exist, NGINX will point out the exact file and line number containing the error. Common NGINX configuration mistakes include:

1. Syntax errors: Such as missing semicolons (;), or unmatched braces (}).
2. Incorrect file paths: Files or directories specified in include or other directives do not exist.
3. Port conflicts: The configured listen port is already in use by another process.

Apache Configuration Check

Use Apache’s apachectl configtest command to check the configuration syntax.

/Applications/ServBay/bin/apachectl configtest

If the configuration is valid, it will display Syntax OK. Otherwise, you'll get detailed error messages. Common Apache configuration errors include:

1. Module load failures: A module specified in the configuration (LoadModule) does not exist or the path is incorrect.
2. .htaccess syntax errors: Syntax errors in .htaccess files within your site directories can cause Apache config check failures or directory access errors.
3. Directory permission misconfiguration: Permission directives like Require, Allow, or Deny within Directory or Files blocks prevent access to web files.

Handling 500 Internal Server Errors

A 500 Internal Server Error is a generic HTTP status code indicating that the server encountered an unexpected condition that prevented it from fulfilling the request. For web applications, this often means that a backend script (e.g., PHP, Python, Node.js) failed to execute properly.

General Troubleshooting Steps

When you encounter a 500 error, follow these steps:

1. Check the Web Server Error Log: This is always the first step in diagnosing a 500 error. Error logs usually contain detailed information about what went wrong, such as script errors, missing files, or permission issues.

   • Caddy: /Applications/ServBay/var/logs/caddy/error.log
   • NGINX: /Applications/ServBay/var/logs/nginx/error.log
   • Apache: /Applications/ServBay/var/logs/apache/error.log Check the most recent log entries for messages containing error or critical.

2. Verify Backend Services (like PHP-FPM) are Running: If your site relies on PHP, make sure PHP-FPM is running.

   ps aux | grep php-fpm

   Look for lines containing php-fpm: master process or php-fpm: pool www. If the process isn’t there, PHP-FPM is either not running or has crashed. You can start PHP via the ServBay UI or using the servbayctl command.

3. Check Backend Script (like PHP) Error Logs: If your web server logs indicate FastCGI or backend script errors, examine the corresponding language error logs.

   • PHP: /Applications/ServBay/var/logs/php/php_error.log Look for Fatal error, Parse error, Warning, Notice, especially those related to the script you’re accessing. Ensure display_errors is off in production but can be enabled for development to see detailed error information (set in php.ini).

4. Check File and Directory Permissions: Web servers typically run under a dedicated user (like _www) and require adequate permissions to read site files/directories and write to upload or log directories.

   ls -la /Applications/ServBay/www/your-site/

   Ensure the web server user has read access to the site root and its files/subdirectories. For uploads or log writing, write permissions are also needed. Use chmod and chown to adjust, but proceed with caution.

500 Error Troubleshooting Tips for Specific Web Servers

• Caddy:

  1. FastCGI Configuration: Check that the php_fastcgi or reverse_proxy directive in your Caddyfile points to the correct PHP-FPM address (usually 127.0.0.1:9000 or unix:/path/to/php-fpm.sock).
  2. PHP-FPM Status: Make sure the corresponding PHP version and PHP-FPM service are running in ServBay.
  3. Reverse Proxy Settings: If using reverse_proxy to proxy traffic to another backend (e.g., Node.js), verify the backend address/port and ensure the service is running.

• NGINX:

  1. fastcgi_pass Directive: Verify the fastcgi_pass directive in nginx.conf or your site's config points to the correct PHP-FPM address.
  2. client_max_body_size: If large file uploads result in 500 errors, this setting might be too small for your needs.
  3. try_files Directive: Ensure the try_files directive is correctly set so requests are routed to the appropriate index file or passed to FastCGI as needed.

• Apache:

  1. mod_rewrite Module: If you're using .htaccess for URL rewriting, confirm that Apache's mod_rewrite is enabled.
  2. .htaccess Content: Erroneous directives in .htaccess files can directly cause 500 errors. Check syntax, especially rules like RewriteRule.
  3. AllowOverride Setting: Make sure the relevant Directory block in your Apache config has AllowOverride set to allow the directives used in your .htaccess file (usually All, or at least includes FileInfo and Limit).

Service Management

After changing configuration files or fixing backend issues, you’ll typically need to restart the web server or related services for changes to take effect.

Restarting Services

Use the servbayctl restart command to restart a specific web server and its related services.

# Restart the Caddy service
servbayctl restart caddy -all

# Restart the NGINX service
servbayctl restart nginx -all

# Restart the Apache service
servbayctl restart apache -all

The -all option attempts to also restart companion services—such as PHP-FPM if FastCGI is configured with Caddy, NGINX, or Apache.

Checking Service Status

Use the servbayctl status command to view the current status of specific services.

# Check Caddy service status
servbayctl status caddy -all

# Check NGINX service status
servbayctl status nginx -all

# Check Apache service status
servbayctl status apache -all

The command output shows if the service is running, stopped, or another status—helpful to confirm successful startups.

Advanced Troubleshooting Steps

If the above steps don’t resolve your problem, try these deeper troubleshooting tips:

1. Review Browser Developer Tools: Open your browser’s developer tools (usually via F12), and inspect the Console and Network tabs. Look for front-end JavaScript errors, detailed HTTP status codes, response headers, and bodies to determine whether the issue is client-side or server-side.
2. Use the curl -v Command: In your terminal, run curl -v your-website.servbay.demo to access your site. The -v option outputs detailed request/response info, including headers and SSL/TLS details. Replace your-website.servbay.demo with your actual ServBay site domain.
3. Temporarily Disable Firewall for Testing: Your local firewall (like macOS built-in firewall) or third-party security software may block incoming connections. Temporarily disable the firewall and test—if the problem resolves, update rules to allow ServBay ports (e.g., 80, 443).
4. Test on Different Browsers/Devices: Try accessing your site from various browsers or devices to confirm if the issue is universal or limited to a particular setup.
5. Check Local DNS or hosts File Settings: If you're using a custom domain (not localhost or an IP), check /etc/hosts or your local DNS settings to verify the domain correctly resolves to 127.0.0.1 or ::1.

Conclusion

Web server issues are a common challenge in local development. By systematically checking configuration syntax, analyzing error logs, verifying service status, and ensuring proper file permissions, most problems can be resolved quickly. Leverage ServBay’s built-in troubleshooting tools and servbayctl command-line utility as your reliable assistants. If you encounter complex issues, consult the ServBay documentation or reach out to technical support for further help.