When something breaks

Start here

furnace init --deep

It repairs what it can (lifts maintenance mode, returns a cell to developer mode and restores the static deployment version, clears foreign modules from app/code, fixes the integration framework's configuration, syncs registry credentials the registry accepts, recaptures a stale golden) and then proves each cell can run an integration test. If every cell fails at once, suspect shared infrastructure before the cells.

Every cell fails at once

After a reboot, MageBox's PHP-FPM masters do not come back; it installs no boot-time unit. nginx answers, nothing is behind it, and every cell renders zero products:

magebox start --all

Otherwise check the containers (docker ps) for the database and OpenSearch, and confirm a cell answers at all:

curl -sk -o /dev/null -w '%{http_code}\n' -H 'Host: m248.test' https://127.0.0.1/

502 means PHP-FPM. 200 with no products means the cell.

Symptom by symptom

Symptom	Cause and fix
PHPUnit executed 0 tests	a declared service is down (doctor: test services); PHPUnit major does not match the platform; a phpunit.xml extension class does not autoload; a non-nullable typed property in a test class on 2.4.6/2.4.7; a sandbox built for a different module set (furnace rebuilds it)
Refusing to restore m248: the golden no longer describes this cell's vendor/	vendor/ was rebuilt after capture. furnace init recaptures when nothing else is wrong; otherwise furnace golden --capture -c m248
a run was interrupted	furnace clean --restore then furnace init; the next run also recovers the cell on its own. An interrupted fresh install leaves the cell without env.php; discovery falls back to the golden copy, so the same two commands work
composer require failed: Problem 1 ...	the solver's message is the customer's install error too; read install-composer-require.log in the run directory. A private companion needs its repository in the extension's root composer.json, in install.repositories, or in the cell
registries: ... rejected its credentials	the token in the cell's auth.json (or the global one) is stale. Refresh the global file and run furnace init; it replaces only what the registry proves. A stale global credential is reported, never copied
X is already installed in the cell -- the golden is not pristine	the golden carries extension residue; doctor shows it under golden purity. Clean the cell, then recapture
browser tests fail identically on every cell	the suite targets the wrong host: a pinned baseURL or an environment variable furnace does not set. The e2e log header records the URL actually used; furnace refuses a config that pins baseURL to a literal
"There has been an error processing your request" on every page	a cell left in production mode without pub/static/deployed_version.txt; furnace init returns it to developer mode
"Unable to proceed: the maintenance mode is enabled"	var/.maintenance.flag survives database restores; furnace init lifts it
search index: invalid (unpatched esconfig.xsd)	libxml 2.12 rejects Magento ≤2.4.7's schema; furnace init applies the 2.4.8 schema, matching the broken file's hash only
setup:di:compile fails on one cell only after a clean install	stray modules in that cell's app/code; the next run purges them, doctor warns about them
platform_check.php says the PHP version is too low	a tool was run with furnace's PHP against a cell that requires a newer one. Gates that run inside a cell use the cell's PHP; if you see this, a gate is not
rector finishes in under a second on a harness run	nothing was scanned. Rector's skip list used to exclude */vendor/* globally, which is where harness modules live; it is now per module path

"PHPUnit executed 0 tests"

This one message has had at least five distinct causes, which is why the gate now reports the reason where it can. In rough order of likelihood:

cause	check
a service the integration config declares is not running	doctor: test services
PHPUnit's major does not match the platform	doctor: phpunit
a phpunit.xml extension class will not autoload	doctor: phpunit
exclude-from-classmap hides PHPUnit's own event classes	init repairs it
the test class fatals during Magento's property cleanup	see writing testable extensions
the tests live at the repository root, not in a module	the gate names the directories; move them under <Module>/Test/Integration
a release dist export-ignores Test/	nothing to run from the registry; certify from a checkout with --release, or ship the tests

A cell will not restore

✗ reset  Refusing to restore m248: the golden no longer describes this cell's vendor/

The cell's vendor/ was rebuilt after the golden was captured. furnace init recaptures automatically when nothing else is wrong; otherwise:

furnace golden --capture -c m248

Do not run two matrices at once

Cells, database servers and OpenSearch are shared. A second run takes a cell lock and reports the cell busy, but the two still compete for CPU and the search engine. Check with pgrep -af "furnace run" before starting one.