Skip to content
Menu

Troubleshooting#

What to do when a bake is refused or a check fails. Each symptom below names the cause, the fix, and a command that checks the result. Start with the exit code: 0 done, 1 refused, 2 tool error. A starter that refuses loudly is easier to feed than one that fails quietly.

Exit code 1: the bake was refused#

A --raw --vue app shows "No Vite build and no dev server"#

Cause: the raw PHP + Vue app loads its page from Vite: from public/build/manifest.json after npm run build, or from the dev server while npm run dev runs. A fresh bake has neither, so src/Vite.php refuses with that sentence instead of printing tags that point nowhere.

Fix: build the front end once, or run the dev server next to composer serve.

Check:

npm install
npm run build
composer serve

http://localhost:8000 shows the app, and http://localhost:8000/api/me answers JSON.

sourdough new refuses before writing anything: no read access to Playbook#

Cause: by default the generated app requires waynestate/playbook, WSU's private shared-values package on git.wayne.edu. Before writing anything, sourdough new checks that this machine can read the package (a Composer credential, then a direct git probe); without read access it refuses with exit 1 and prints the how-to.

Fix: follow the printed how-to to get read access, then rerun the same command.

Check:

sourdough new my-app --dry-run --json

--dry-run runs the check but never refuses, and its JSON plan carries a playbook key with the mode, the access status and the probe that answered. Once the app exists, composer playbook (the script @composer show waynestate/playbook --no-interaction) shows whether Playbook is installed.

git.wayne.edu is unreachable during the access check#

Cause: the Playbook access check cannot reach git.wayne.edu. Sourdough still generates the app, but warns that composer install will need the connection.

Fix: restore the connection to git.wayne.edu, then install the app's dependencies.

Check:

composer install

Run it in the generated app; it completes without the Playbook fetch failing.

--playbook and --no-playbook together#

Cause: the two flags are mutually exclusive and are refused with exit 1. --playbook is kept for compatibility and changes nothing, because Playbook is now the default.

Fix: drop one of the flags.

Check:

sourdough new my-app --dry-run

Exits 0 and prints the plan.

An invalid flag, a non-empty target, or a bad app name#

Cause: exit 1 also covers invalid flags, a non-empty target (Sourdough refuses to generate into a directory that already has files), and an app name that fails validation. The name (from --name, from the plan, or from the basename of <dir>) must start with a letter or number and use only letters, numbers, spaces, dots, dashes and underscores, at most 63 characters; anything else is refused before anything is written.

Fix: correct the flags, point dir at an empty directory, and rename the app to something the allow-list accepts.

Check:

sourdough new my-app --dry-run

Prints the plan and writes nothing.

The model gave up (--describe)#

Cause: if the answer from the model is not valid JSON, does not match the schema, or the model gives up after one retry, Sourdough refuses with a message pointing you to --plan=<file> (exit 1).

Fix: write the plan yourself and pass it in:

sourdough new my-app --plan plan.json

--plan reads the file, validates it against the schema, and continues the normal generation flow using the plan's permutation and name.

Check: the same command exits 0 when the plan is valid.

Exit code 2: a tool error#

sourdough manifest without --check#

Cause: without --check the command answers "Use sourdough manifest --check to check the app against its manifest." and exits 2. A missing manifest in the directory is also a tool error (exit 2).

Fix: run the command with --check, inside the generated app (or pass the app directory as an argument).

Check:

sourdough manifest --check

Exits 0 and prints Clean: every managed file matches the manifest.

--json without --dry-run#

Cause: --json is only available with --dry-run; without it the command exits 2.

Fix: add --dry-run.

Check:

sourdough new my-app --dry-run --json

Prints the plan as JSON.

The model could not be reached (--describe)#

Cause: --describe needs the SOURDOUGH_LLM_BASE_URL, SOURDOUGH_LLM_API_KEY and SOURDOUGH_LLM_MODEL environment variables (no defaults, no key in code) and a reachable OpenAI-compatible endpoint. When the endpoint cannot be reached, the command prints The model could not be reached: plus the underlying error and exits 2.

Fix: set the three variables and point them at a working endpoint (a hosted API, a local server, or WarriorGPT), then rerun. Any OpenAI-compatible endpoint works; Sourdough only needs the base URL, key, and model.

Check:

sourdough new --describe "A blog with posts and comments" --plan-only

Prints the plan as JSON without writing anything.

Drift: the manifest and the Squire copy#

sourdough manifest --check exits 1 in a generated app#

Cause: a managed file changed or is missing. The output lists one line per file, changed <file> or missing <file>. Seeded files (.env.example and README.md) are never reported: they're yours.

Fix: nothing, if the change is deliberate. sourdough feed three-way merges your edits with the template's, so a drifted managed file is fine; the check just names the files a feed will merge rather than replace. If the change was a mistake, restore the file from your version control.

Check:

sourdough manifest --check

Exits 0 when every managed file matches the manifest.

composer squire-copy:check exits 1 (maintainers of Sourdough)#

Cause: the committed copy at templates/squire/ has drifted from a fresh export from the installed waynestate/squire package. The check is part of composer ci.

Fix: rewrite the copy from the installed package, then commit templates/squire/:

composer squire-copy:sync

Check:

composer squire-copy:check

Exits 0 when the committed copy matches.

PROCTOR's preflight-pinned check warns on a bare tag#

Cause: PROCTOR 0.4 to 0.7's preflight-pinned check wants a 40-hex SHA and warns on a bare tag (0.8 also accepts a full release tag such as @0.3.0, and still warns on a branch, ~latest or a partial version such as 0.3). New apps pin the Preflight CI components to the 0.9.0 release SHA (fb73b538f3980292119b5b306ff64383d760a214, with the tag in a trailing comment), which every PROCTOR accepts.

Fix: pin the Preflight component includes to the release SHA, with the tag in a trailing comment. Moving a pin is a deliberate commit.

Check:

composer ci

Run it in the generated app; the PROCTOR check passes.

Feeding: sourdough feed#

sourdough feed exits 2: "Commit or stash your changes first"#

Cause: the app's git tree is not clean (a modified, staged or untracked file under the app folder). Feed only runs on a clean tree, so git diff shows exactly what it did and git restore undoes it.

Fix: commit or stash your work, then feed. --dry-run still plans on a dirty tree, with a note.

Check:

git status --porcelain

Prints nothing when the tree is clean.

sourdough feed exits 1: a conflict#

Cause: you and the template changed the same lines of a file, or feed had no base to merge from (you edited the file before your first commit), so it marked both versions instead of guessing. The plan line says which.

Fix: open each conflict file, keep what it should be, delete the <<<<<<< app, ======= and >>>>>>> sourdough <version> lines, run your checks and commit. For a binary file, compare it with <file>.sourdough-new, keep one, and delete the copy.

Check:

git diff --check

Prints nothing when no conflict markers are left.

sourdough feed exits 2: "Finish the last feed first"#

Cause: a managed file still holds a marker from an earlier feed (>>>>>>> sourdough <version>), or a .sourdough-new copy is still lying around. Feeding on top of an unresolved conflict would bury it.

Fix: resolve the listed files as for a conflict above, delete any .sourdough-new copies, commit, then feed again.

Check:

sourdough feed --dry-run

Exits 0 or 1 (a plan) instead of 2.

sourdough feed exits 2: "only runs inside a git repository" or "No Sourdough manifest"#

Cause: feed stands on git and on a manifest. An app outside git cannot be fed, and neither can one Sourdough did not make (WELD included) until it has a manifest.

Fix: git init and commit the app first. For an app with no manifest, adopt it: sourdough adopt --shape <shape>, commit .sourdough/, then feed. See Adopt an existing app.

Check:

sourdough manifest --check

Exits 0 or 1 when the app has a manifest, 2 when it has none.

Adopting: sourdough adopt#

sourdough adopt exits 1: "--shape is required" or "Unknown shape"#

Cause: adopt never picks a shape; you name what the app already is. Without --shape it says what the app's files point at (This app looks like laravel-inertia (it has artisan and inertiajs/inertia-laravel).). A shape that is not one of the five is refused with the list, and a retired one with its replacement.

Fix: pass one of raw, raw-vue, laravel-blade, laravel-blade-vue, laravel-inertia. These are the manifest's template values, not sourdough new's flags.

Check:

sourdough adopt --shape raw --dry-run

Exits 0 with the report.

sourdough adopt exits 1: an oven or a name it cannot bake#

Cause: --sail or --docker on a raw shape (--sail and --docker are for the Laravel paths: the raw paths run on plain PHP.), both ovens (Choose one of --sail or --docker, not both.), or a name sourdough new would refuse, followed by Pass --name "<a valid name>". The name defaults to the folder's basename, so a folder called my app (old) is refused.

Fix: drop the oven (an app with its own Docker setup needs neither), or pass --name with letters, numbers, spaces, dots, dashes and underscores, at most 63 characters, starting with a letter or number.

Check:

sourdough adopt --shape laravel-blade --name parking-permits --dry-run

Exits 0 with the report.

sourdough adopt exits 1: "does not exist" or "is a file, not a directory"#

Cause: <dir> is not there, or it names a file. Adopt takes the app's root folder.

Fix: pass the app's root folder, or run adopt inside it with no <dir>.

Check:

sourdough adopt --shape raw --dry-run

Exits 0 with the report.

sourdough adopt exits 1: "already has a Sourdough manifest"#

Cause: Sourdough made or adopted this app already. Adopting over a manifest would lose the record feed stands on, so adopt has no --force.

Fix: bring it up to date with sourdough feed. To adopt it again with another --shape or --name, delete .sourdough/, commit, and run adopt again.

Check:

sourdough feed --dry-run

Exits 0 (fresh) or 1 (a plan): the app already has its record.

sourdough adopt exits 1: "is left from a manifest that is gone"#

Cause: .sourdough/base/ is there but .sourdough/manifest.json is not. Those base copies belong to a record that is gone, and a later feed would merge against them as if they were still true.

Fix: delete .sourdough/, commit, and run adopt again.

Check:

sourdough adopt --shape raw --dry-run

Exits 0 with the report.

sourdough adopt exits 1: "only runs inside a git repository"#

Cause: the app is not in git. Adopt wants the adoption to be one commit you can review, and every later feed to be undoable.

Fix:

git init
git add -A
git commit -m "Before Sourdough"

Check:

sourdough adopt --shape raw --dry-run

Exits 0, with no note: Not inside a git repository line.

sourdough adopt exits 1: "Commit or stash your changes first"#

Cause: the tree has uncommitted or untracked changes, listed under the message (up to ten, then ... and N more). The hashes describe the files on disk, so uncommitted edits would be adopted as if they were committed, and the adoption should be a commit of its own.

Fix: commit or stash, then adopt.

Check:

git status --short

Prints nothing.

sourdough adopt exits 2: git, the folder or the bake#

Cause: one of these:

  • sourdough adopt needs git on PATH (or SOURDOUGH_GIT set to it): adopt checks the tree, and feed, which comes next, merges with git.
  • Cannot write "<dir>/.sourdough/manifest.json": the folder is not writable.: adopt writes only that file.
  • sourdough adopt failed: could not bake a fresh <shape> app to compare with: ...: the Laravel shapes bake a fresh laravel/laravel skeleton, so they need Composer and the network (or a warm Composer cache), the same as sourdough new.
  • sourdough adopt failed: ... after the report was planned: the manifest could not be written.

Fix: put git on PATH or set SOURDOUGH_GIT; fix the folder's permissions; for a Laravel shape, check that composer runs (or set SOURDOUGH_COMPOSER) and that the network or the Composer cache is there.

Check:

git --version
composer --version

Both print a version.

Many files are yours, and a note says the name may be wrong#

Cause: the template writes the app's name into files (composer.json, public/index.php, the README), and --name defaulted to the folder's basename. If the app goes by another name, every file that carries it differs. Adopt flags each one (differs; the template writes the app name here as "<name>", and your file does not have it), and two or more add note: <n> files differ where the template writes the app name.

Fix: delete .sourdough/, commit, and adopt again with --name set to the name in composer.json. A yours file is never lost or overwritten either way; the right name only lets more files match.

Check:

sourdough adopt --shape raw --name parking-permits --dry-run

The name note is gone and more files are match (add -v to list them).

Almost everything is yours on an older Laravel app#

Cause: adopt compares with today's laravel/laravel skeleton and today's PHP floor from CREED's policy. An app several majors behind differs almost everywhere. That is correct: yours files are safe, and feed never touches them.

Fix: upgrade first with Booster, one hop at a time, then adopt (or, if already adopted, feed: each file that now matches is recorded and managed from then on).

Check:

sourdough adopt --shape laravel-blade --dry-run

The summary line shows more match than before the upgrade.