Stratosv1.4.0

Help

Troubleshooting

What to try first when something looks off.

The status pill is red

  1. Click the red pill to expand the error.
  2. Most service errors include the offending line of stderr. "address already in use" means another tool is on the same port; "permission denied" means the privileged helper is missing.
  3. Click Restart on the service. If the error persists, reinstall from Settings → General → Reset stack.

A site returns 502 Bad Gateway

This almost always means PHP-FPM is not running or the FPM socket path in the nginx config is wrong for the active PHP version.

  1. Check the PHP-FPM service card. If it's red, restart it.
  2. Confirm the version pinning in stratos.yml matches an installed PHP version. Stratos only ships versions you've installed from Settings → PHP.
  3. Look at the FPM error log: Logs → php-{version}-fpm-error.

The .test domain doesn't resolve

  1. Confirm dnsmasq is running (green pill).
  2. Run dig myapp.test @127.0.0.1 in the terminal. The answer should be 127.0.0.1.
  3. If not, the privileged helper may not be installed. Reinstall from Settings → General → Reinstall helper.
  4. If you've switched DNS providers (e.g. a corporate VPN), the resolver may be upstream. Stratos's resolver runs on port 53 only for the test zone; everything else goes through the system resolver.

Mail is not appearing in the inbox

  1. Confirm the MailCatcher service is running.
  2. Confirm your app's MAIL_HOST is 127.0.0.1 and port is 1025 (the default).
  3. Try sending a test from the terminal: echo "test" | nc -w 1 127.0.0.1 1025. You should see a new entry in the inbox.

The app launches but nothing is in the menu bar

  1. Stratos lives in the menu bar, not the Dock. Look in the top-right of the menu bar.
  2. If the icon is hidden by macOS, drag the menu bar down to reveal it (some users do this in System Settings → Control Center → Menu Bar Only).

Reset everything

If all else fails, Settings → General → Reset stack stops every service, deletes the bundled binaries, and re-downloads them. Your sites, configs, and mail database are untouched. The reset takes about 90 seconds.

Still stuck?

Email support@stratos.app with the output of stratos status and a description of what you expected vs. what you got.