Troubleshooting

Fixes for the problems you're most likely to meet, in the order people usually hit them. Two commands help with almost all of them: laramonster status shows what's running and any warning, and laramonster logs shows what went wrong.

A port is already in use

What you see: setup's Ports step says “Port 8080 (HTTP) is already in use”, the dashboard shows a red banner “Port 8080 is used by another program”, or laramonster status prints the ports in yellow. No site opens.

Why: another program listens on the port LaraMonster's web server needs. LaraMonster keeps running but can't serve sites until it has both ports. Common culprits:

Fix 1: move LaraMonster to free ports (quickest)

In setup's Ports step (or the banner's Fix it), click Use 8081 and 8444; LaraMonster suggests the nearest free ports. Or from a terminal:

$ laramonster port 8081
$ laramonster port --https 8444
$ laramonster status
  ports      http 8081, https 8444

Sites then open at http://blog.localhost:8081. Update APP_URL in projects that include the port.

Fix 2: stop the program that holds the port

LaraMonster names the program when your system lets it see it. If it doesn't (programs of another user or of the system are hidden without administrator rights), these commands show it. Replace 8080 with the busy port.

$ sudo lsof -nP -iTCP:8080 -sTCP:LISTEN
COMMAND   PID   USER   FD   TYPE   DEVICE SIZE/OFF NODE NAME
nginx    1234   you    6u  IPv4  0x1a2b3c      0t0  TCP *:8080 (LISTEN)

# Installed with Homebrew? Stop the service and keep it off at login
$ brew services list
$ brew services stop nginx           # or httpd, php, mysql…

# Laravel Valet
$ valet stop

# A Docker container
$ docker ps --filter "publish=8080"
$ docker stop <container-id>

# Anything else: stop it by its PID (from step 1)
$ kill 1234

$ sudo ss -ltnp 'sport = :8080'
State  Recv-Q Send-Q Local Address:Port Peer Address:Port Process
LISTEN 0      511          0.0.0.0:8080      0.0.0.0:*     users:(("nginx",pid=812,fd=6))

# A system service: stop it now and keep it off at boot
$ sudo systemctl disable --now nginx     # apache2 on Debian/Ubuntu, httpd elsewhere

# Not sure which service? List the running ones
$ systemctl list-units --type=service --state=running

# A Docker container
$ docker ps --filter "publish=8080"
$ docker stop <container-id>

# Anything else: stop it by its PID (from step 1)
$ kill 812

PS> Get-Process -Id (Get-NetTCPConnection -LocalPort 8080 -State Listen).OwningProcess
Handles  NPM(K)  PM(K)  WS(K)  CPU(s)    Id  SI ProcessName
    310      22  14560  21988    0.42  4321   1 httpd

# Apache from XAMPP, WampServer or Laragon: stop it in their control panel, or
PS> Stop-Service -Name Apache*

# "System" (PID 4) means IIS or another Windows web service. As administrator:
PS> iisreset /stop

# A Docker container
PS> docker ps --filter "publish=8080"

# Anything else: stop it by its PID (from step 1)
PS> Stop-Process -Id 4321

Then click Check again in LaraMonster, or run laramonster reload. The banner disappears as soon as both ports are free.

The browser says the connection isn't private

What you see: “Your connection is not private” (NET::ERR_CERT_AUTHORITY_INVALID) or Firefox's “Warning: Potential Security Risk Ahead” on an https:// site.

1. Check the trust status

   SettingsHTTPS certificates shows System and Browsers. Anything not Trusted? Click Trust certificate authority, or run laramonster trust.

2. Firefox or Chrome on Linux shows “Needs certutil”

   Install Browser certificate tools from Tools, then trust again.

3. Restart the browser completely

   Browsers read trusted certificates when they start. Quit it fully (on macOS, ⌘ Q), not just the window.

4. Still there?

   Trust it by hand with the commands in HTTPS → Trust it by hand.

PHP's own requests (Guzzle, Http::get()) to another local https:// site use the system store, so they work once System is trusted.

“No site is configured” or 404 for a whole site

• Is the project in a parked folder, or linked? laramonster sites lists every site and its address.
• The site name comes from the folder name: My Shop is my-shop.localhost.
• Is the site switched off on the Sites page?
• Using .test? Check that names resolve: see below.

502 Bad Gateway, or PHP won't start

1. Look at the dashboard warnings

   A site pinned to a PHP version that isn't installed, or a PHP build that can't start, shows a warning with the fix.

2. Read the PHP log

   laramonster logs php84-fpm (use your version). A missing extension or a bad php.ini value shows up there.

3. Undo a recent PHP setting

   Empty the value you changed last in PHP settings.

4. Windows: install the Visual C++ runtime

   PHP on Windows needs it. LaraMonster offers Install the Visual C++ runtime on the PHP page when it's missing.

The terminal uses another PHP

What you see: php -v in a project shows a different version than the site uses.

$ which php                        # Windows: where.exe php
/usr/bin/php                       # not LaraMonster's shim
$ laramonster which                # what LaraMonster would use here

• Open a new terminal: terminals opened before setup keep their old PATH.
• Run laramonster setup (or setup's Terminal commands) if you skipped it.
• Another tool adds its PHP after LaraMonster in your shell profile (Herd, Homebrew, asdf, phpenv). Put LaraMonster's bin folder last in ~/.zshrc or ~/.bashrc so it wins, or use laramonster php.

.test addresses don't open

$ laramonster dns status
$ laramonster dns setup            # run it again; asks for your password

• On Windows and Linux without systemd-resolved, LaraMonster uses the hosts file: click Sync hosts file in Settings after adding sites.
• A VPN or a custom DNS setting in your browser (“secure DNS”) can bypass your system's resolver. Turn it off for testing, or use .localhost, which never needs DNS.

“Connection refused” from the database

• Start the service on the Services page (and turn on its switch so it starts with LaraMonster).
• Compare DB_PORT with the port the service card shows: it may run on another port because a system MySQL holds 3306.
• Use DB_HOST=127.0.0.1, not localhost: localhost makes MySQL clients look for a socket file instead.
• After changing .env, clear cached config: php artisan config:clear.

Emails don't show up in the inbox

• Is Mail set up and running? Open the Mail page.
• Check MAIL_MAILER=smtp, MAIL_HOST=127.0.0.1 and MAIL_PORT=1025; see Mail inbox.
• Queued mail (ShouldQueue) only sends when a worker runs: start one from Jobs & queues, or run php artisan queue:work.

LaraMonster won't start

• Run laramonster start in a terminal: it prints why it stopped.
• “LaraMonster is already running”: one is already up; open the app, or laramonster stop first.
• Read laramonster logs laramonster.
• macOS: if it closes right after opening, make sure it's in Applications and you allowed it under Privacy & Security; see Installation.

Starting over

To reset LaraMonster without losing projects: stop it, rename its home folder (see where its files live), and open it again. Setup runs as on the first day. Your projects are untouched; databases stay in the renamed folder until you delete it.

Getting help

Open an issue on GitHub with your system, LaraMonster's version (bottom of the sidebar) and the output of:

$ laramonster status
$ laramonster logs laramonster -n 200