← kalimera

TROUBLESHOOTING

Problems that have come up while scaffolding real apps with kalimera — what causes each one and how to fix it.

Sail fails with "all predefined address pools have been fully subnetted"

failed to create network <app>_sail: Error response from daemon: all predefined address pools have been fully subnetted
WHEN
Running `sail up -d --wait` while scaffolding a new app (kalimera Step 5, "Building and starting the Sail containers").
WHY IT HAPPENS
Every Sail project gets its own dedicated Docker bridge network, and Sail never removes it once a project is deleted or abandoned. Docker Desktop's default address pool only holds a limited number of /20 subnets — roughly 27–31 on a typical install — before every predefined pool is already claimed by leftover networks, and Docker refuses to create a new one.
FIX
Run `docker network ls` to see how many networks exist, then `docker network prune` to remove the ones with no containers attached (Docker refuses to prune a network still in use, so this only clears genuinely orphaned networks from finished or abandoned projects). Re-run `sail up -d --wait` afterwards. If this keeps recurring, raise `default-address-pools` in Docker Desktop's daemon settings so it allocates from a larger pool.

`kalimera new --continue` hangs or errors with "Required." in a non-interactive shell

Required. / Scaffolding stopped. Fix the issue above and re-run, or continue manually inside the app directory.
WHEN
Resuming a failed scaffold with `kalimera new --continue` — either without the app name as a second argument, or while running the command from inside the app directory itself.
WHY IT HAPPENS
Without an explicit app-name argument, kalimera falls back to an interactive prompt asking what the application should be named. In a non-interactive shell (CI, a scripted run, an agent without a TTY) that prompt has nothing to read and fails immediately. Passing just `--continue` doesn't skip this — only a name/path positional argument does. And because the target path is resolved relative to the current working directory, running from inside the app directory itself resolves to a nested, wrong path even when a name is supplied.
FIX
Run it from the parent directory with the app name as the second argument: `cd ~/www && kalimera new <app-name> --continue --defaults`. `--continue` reuses the answers saved in the app's `.kalimera.json`, so `--defaults` only matters for the final "Scaffold the application now?" confirmation — include it anyway so nothing prompts.

Step 10 fails with "There are no commands defined in the boost namespace"

ERROR There are no commands defined in the "boost" namespace. — thrown by `sail artisan boost:install --guidelines --skills --mcp --no-interaction`.
WHEN
kalimera Step 10, "Installing Laravel Boost", immediately after `composer require laravel/boost --dev`.
WHY IT HAPPENS
The `composer require laravel/boost --dev` that runs just before this step has, at least once, reported success ("Nothing to install, update or remove") without actually adding the package to composer.json or vendor/ — an intermittent Composer resolution flake we haven't fully root-caused yet. Since the package was never installed, its service provider is never discovered and none of its artisan commands exist.
FIX
Re-run the same command by hand inside the app directory — `sail composer require laravel/boost --dev` — and confirm `laravel/boost` now appears in composer.json before continuing. On every occurrence so far, the second attempt has succeeded immediately. Then resume the scaffold (see the previous entry).

PHPStan exits with no output at all when a scaffolded path like `src` is deleted later

vendor/bin/phpstan analyse (via sail composer phpstan) exits with code 1 and prints nothing — no errors, no message, just a bare failure.
WHEN
Running `composer phpstan` / `composer quality` after removing an empty `src/{Domain,...}` directory that kalimera scaffolded for the Core structure, once the project ends up not using it.
WHY IT HAPPENS
kalimera only strips the `- src` path from `phpstan.neon.dist` (and `rector.php`) automatically when the Core structure was never chosen during scaffolding. If it was scaffolded and `src/` is deleted afterwards, `phpstan.neon.dist` still lists a path that no longer exists on disk, and PHPStan — run through Sail's docker exec — fails on that with a bare exit code and no output instead of a clear error, which reads as a crash rather than a config problem.
FIX
Remove the stale `- src` line from `phpstan.neon.dist` (and `__DIR__.'/src'` from `rector.php` if present) to match the current codebase, or restore an empty `src/.gitkeep` if the Core structure is still wanted. Confirm with `sail composer phpstan` — it should print real output (pass, or a list of errors) instead of failing silently.

A previously working app suddenly fails to start with "port is already allocated"

Error response from daemon: driver failed programming external connectivity on endpoint <app>-redis-1: Bind for 0.0.0.0:6382 failed: port is already allocated
WHEN
Running `sail up -d` on an app that started fine before, after a different kalimera-scaffolded project has been started in the meantime.
WHY IT HAPPENS
kalimera picks host ports by opening a socket against 127.0.0.1 to see what is listening *at that moment* (`NetworkPortChecker`). A port held by a project whose containers are currently stopped looks completely free, so a later scaffold happily writes the same `APP_PORT` / `VITE_PORT` / `FORWARD_*_PORT` values into its own .env. Nothing detects the clash until both projects are up at once — then whichever starts second fails. Two apps scaffolded weeks apart can end up with byte-identical port blocks.
FIX
Pick free ports for one of the projects and edit its `.env` (`APP_PORT`, `VITE_PORT`, `FORWARD_REDIS_PORT`, `FORWARD_DB_PORT`), then `sail up -d`. To see what is actually taken right now: `docker ps --format '{{.Names}}\t{{.Ports}}'`. Choosing ports for the app you are *not* currently running avoids disturbing a live one. Note this affects only .env, so it is safe and reversible.