Plugin troubleshooting
Manifest checks, runtime failures, logging and cache maintenance.
Start with the manifest
php artisan signals:plugin check acme/review-test
php artisan signals:plugin check acme/review-test --wire --json
php artisan signals:plugin list
Plain check discovers the package and validates signals.yaml without calling register() or boot(). Add --wire to instantiate the plugin and call only register() with a scoped registrar. Core wraps that check in a database transaction that is rolled back and a runtime checkpoint that is restored on success or failure. Registration output is discarded. The check does not call boot(), install migrations or prove that handlers execute successfully; keep registration free of external side effects.
--json prints package, valid, errors, issues and wire. errors is an object keyed by rule, while issues preserves every diagnostic as {rule, path, message}. wire contains ran, ok, exception and message: without a wire run, ran is false and ok is null. Manifest validation can pass (valid: true) while registration fails (wire.ok: false). Require both to be true when using --wire in CI. The command exits unsuccessfully for either manifest or wiring failure.
Malformed sections are reported as {section}.malformed, with paths such as schedules[0].frequency; unknown declaration fields use {section}.unknown_fields. These diagnostics cover shape/type errors before hydration as well as section validation. Consult the generated complete validation rule table rather than matching only one error string. Regenerate the schema and table with php artisan signals:plugin-schema; use --check to detect drift without writing.
Locate failures
A registration or boot exception is logged as Failed to boot signals plugin; skipping. by PluginBootstrapper, with the package and exception message. A registration or boot() exception leaves the plugin enabled in storage but restores the runtime checkpoint for that bootstrap. A separate failure while parsing an invalid manifest can disable an incompatible plugin. signals:plugin list includes a Health column, and the plugin card shows "Didn't start" with a check --wire hint for startup failures. Inspect health separately from the stored enabled state.
The last startup failure is cached per tenant and package for seven days. It records the stage (manifest, preflight, consent, register or boot), exception class, message truncated to 500 characters, timestamp and count. A successful boot clears it. This is a cached diagnostic, not a status change or a permanent database history.
The destination follows config/logging.php. With the single file channel, inspect storage/logs/laravel.log; deployments using another channel must inspect that channel's destination. Plugin-authored logs can carry a plugin key through the context logger; bootstrap and hook diagnostics use package. Under Octane, each request starts and ends with a fresh request ID, so log entries always carry the ID of the request that wrote them.
PluginHookDispatcher isolates a throwing hook and logs Plugin hook failed; isolating failure from core operation.. Hooks, schedule callbacks and PluginJob executions share the consecutive-failure counter. A successful execution clears that package's counter. At plugins.hook_failure_threshold (default 10, configured by PLUGINS_HOOK_FAILURE_THRESHOLD in config/plugins.php), it attempts to disable an enabled plugin. This threshold is configuration, not a PHP constant. Slow handlers log a warning after plugins.hook_timeout_seconds (default 5); they are not forcibly interrupted.
Refresh discovery and workers
php artisan signals:plugin-cache-clear
php artisan signals:plugin-cache
php artisan octane:reload
PLUGINS_CACHE_ENABLED controls plugins.cache.enabled, which defaults to true. The manifest cache holds discovered enabled plugins. Clear and rebuild it after editing local signals.yaml, changing enable state outside the lifecycle/UI, or deploying package changes. Normal lifecycle operations refresh the cache themselves. In Cloud, run maintenance with the intended tenant context.
Reload Octane workers after PHP code changes so long-lived workers load the deployed classes. Cache regeneration alone does not reload PHP classes.
Exercise package behavior
php artisan signals:plugin test acme/review-test --compact
php artisan signals:sdk-stubs --check
The package test command uses the development-only PluginTestCase harness, isolates the package and returns Pest's exit status. It refuses production and cached configuration. See Testing plugins for HTTP fakes, permission checks and the generated signals-rental/plugin-sdk editor/PHPStan package. Run signals:sdk-stubs after changing the framework SDK surface; the stub package supplies types, never runtime classes.