Troubleshooting
Start with the error text, confirm its cause, then make the smallest safe correction. These entries apply to Pulsar 0.4.1 and link package failures to their source-backed recovery path.
A generator says a Service or Domain does not exist
| Symptom | Likely cause and confirmation | Safe correction and prevention | Source |
|---|---|---|---|
Service [Name] does not exist! | The named Service directory is absent. Confirm the Service spelling and generated tree. | Generate the intended Service or use its exact name; do not create a look-alike directory manually. Keep generator names in the application plan. | Service exception |
Domain [Name] does not exist! | The named Domain directory is absent. Confirm it before a Domain-scoped generator. | Generate the Domain first, then rerun the intended generator. Preserve the canonical Domain name in the command. | Domain exception |
A generator refuses a name, duplicate, or stub
| Symptom | Likely cause and confirmation | Safe correction and prevention | Source |
|---|---|---|---|
Invalid name '…' or a reserved-keyword message | The input contains forbidden characters, path traversal, an empty result, or a PHP keyword. Re-read the exact input. | Choose a valid PHP-oriented name; do not strip characters or bypass validation. Keep names explicit in scripts. | Name validation |
… already exists in …! | The target file, Service, or generated artifact already exists. Inspect that target and its callers. | Keep the existing file or deliberately rename the new work. Do not overwrite it or run a forceful operation before reviewing the diff. | Duplicate-file exception, Service duplicate exception |
Stub file not found: … | A required package stub cannot be read. Confirm the installed package version and path. | Reinstall or correct the package installation using Composer; do not copy an unverified stub into the application. Pin and review package updates. | Stub exception |
The installer cannot safely patch bootstrap files
| Symptom | Likely cause and confirmation | Safe correction and prevention | Source |
|---|---|---|---|
Cannot safely patch [bootstrap/app.php] | The file is missing, unreadable, malformed, or its application chain cannot be parsed or safely merged. The error names the path and reason. | Stop before any destructive action: the installer reports that no files changed. Add the exact listener and Command discovery calls plus PulsarServiceProvider manually, then test the application. Keep a conventional, reviewable bootstrap chain. | Safe fallback exception, installer tests |
Existing withEvents() or withCommands() wiring cannot merge | Existing arguments are not an editable array or more than one call exists. Confirm the current bootstrap shape. | Preserve the application-owned wiring and add the documented Pulsar paths manually once. Do not delete custom bootstrap code to make the installer pass. | Installer merge logic |
| A dry run shows an unexpected diff | The application has existing bootstrap or provider state that changes the plan. | Do not apply it. Compare the dry-run diff, correct the application-owned state, and rerun the preview. Use --force only after reviewing the generated provider it replaces. | Installer reference |
Adapter options must be paired
| Symptom | Likely cause and confirmation | Safe correction and prevention | Source |
|---|---|---|---|
Options [--contract] and [--domain] must be provided together. | Only one Adapter binding option was supplied. Review the command arguments. | Supply both options for a Contract-backed Adapter, or omit both when that binding is not needed. Keep the pair together in automation. | Adapter generator |
Escalate a reproducible defect
If the safe correction does not resolve the symptom, use the package issue tracker. Include version context and a minimal reproduction, and redact sensitive output before submitting it.