OperateGuide 11 / 12

Troubleshooting

Common setup, generation, database, and state problems.

01

PowerShell blocks pnpm

Windows may block pnpm.ps1 under the current execution policy. Use pnpm.cmd without changing the machine policy.

pnpm.cmd install --frozen-lockfile
pnpm.cmd stackiln --help
02

Docker or PostgreSQL is unavailable

Start Docker Desktop or the Docker Engine first. Confirm the database is healthy and that DATABASE_URL uses the same host, port, database, user, and password as the compose service.

docker version
docker compose up -d --wait db
docker compose ps
03

Doctor reports changed files

Run inspect or doctor with --json to get an exact list. Review the product's Git history and keep deliberate customisations. Do not regenerate over the destination or replace those files blindly.

04

Generation fails

  • Run the same create command with --plan first.
  • Check that the destination does not already exist.
  • Use only implemented presets and modules.
  • Install with the repository lockfile before invoking the CLI.
  • Use --json when integrating the planner with another tool.
05

Email does not arrive locally

Check LOCAL_MAILBOX_DIR and inspect the local mailbox outside application source. Production delivery requires the Resend provider values; never use a production key in a committed environment file.