Troubleshooting

Most Muster problems look the same from the outside: every screen is green and nothing is actually being watched or delivered. Work out which of the three moving parts is missing: the scheduler, the queue or the mail transport.

Nothing ever goes late or missed

monitors:evaluate is not running. It runs every minute on the scheduler, and it is the only thing that notices a missing check-in. Check that the scheduler is enabled for the Muster environment in Laravel Cloud. You can run php artisan monitors:evaluate once by hand to confirm the logic works; it prints how many state transitions it recorded.

A monitor is stuck on pending

A monitor you created by hand has no due time until its first check-in, so it can never go missed. Send it one heartbeat and the clock starts. See Connecting your apps.

Monitors go missed but no alert arrives

Open the monitor and check that the channel has a failure type ticked and a destination saved (Configured shows beside it). Then look at the delivery status, which the MCP monitor_history tool reports per event:

• pending: nothing is consuming the queue. Check the managed queue is attached and running.
• retrying or failed on an email alert: the mail transport is not one Muster sends through. A Scalpels-managed installation uses the default Scalpels mailer and needs nothing set. On a standalone installation, a non-delivery mailer such as log or array, or an undefined mailer, is rejected so Muster does not mark an email as delivered when no message can leave the application. See Configuration.
• retrying or failed on a webhook alert: see the next section.

Webhook alerts need no mail configuration and work as soon as the queue is draining.

My webhook endpoint is called but Muster says it failed

Muster treats any non-2xx response as a failure and retries three times before giving up. It does not follow redirects, so a 301 or 302 from your endpoint counts as a failure too: use the final URL, and return 200. The request has 3 seconds to connect and 10 seconds to complete.

I get one alert, then nothing while it stays missed

That is intended. Muster sends one alert per channel per incident and one recovered alert when it ends. It does not repeat while a monitor stays missed.

The weekly digest never arrives

The digest needs at least one monitor, a durable queue that is being drained, and a mail transport Muster sends through. Muster refuses to publish digests on the sync, deferred, background and null queue drivers. On a Scalpels install the managed queue is durable and the default Scalpels mailer delivers, so the usual cause is that no monitor has been created or that no active user has a real email address. The digest goes only to active users whose email address is real.

The digest links to the wrong address

The link uses APP_URL. Make sure it matches the address you use for Muster, including after you add a custom domain.

A connected application registered no monitors

• Both MUSTER_URL and MUSTER_TOKEN must be set and non-empty in that application. Run php artisan config:clear there after muster:install. If only one is set, the application logs Muster is half-configured.
• MUSTER_URL must be the full endpoint, ending in /api/schedule-events.
• The client reports scheduled commands only, on their next scheduled run, so that application's own scheduler has to be running. Running the command by hand reports nothing.
• Reporting fails quietly so it can never break your command. Failed reports are logged at debug level in the connected application.

composer require artisan-build/muster-client cannot find the package

It is not on Packagist yet. Install it from your fork's packages/muster-client directory with a Composer path repository, as described in Connecting your apps.

muster:install says authorization failed

You have three minutes to sign in to Muster and approve the request after the authorization URL is printed. The browser has to run on the same machine as the command, because the approval is returned to a listener on 127.0.0.1. If it fails, the .env file is left unchanged; run the command again.

A heartbeat answers 401 Unauthenticated

The token is missing or wrong, was issued by a different Muster installation, or is not a muster.check-in token. The same answer comes back for a monitor id that does not exist and for a disabled monitor. Check the id in the monitor's address and that the monitor is enabled.

I edited a scheduled command and now there are two monitors

A connected command's monitor is identified by the exact command string. Changing only its schedule updates the same monitor; changing the command or its arguments creates a new one, and the old one stays behind and eventually goes missed. Disable the old one. Monitors cannot be deleted.

I cannot sign in and there is no sign-up link

Muster has no public sign-up. See Getting started for how the first account is created.