Troubleshooting

OverflowException from unique()

OverflowException: Maximum retries of 10000 reached without finding a unique value

Cause: the unique generator state accumulates across tests instead of resetting between them.

Fix: switch to the FactoryTransactionStrategy — it resets unique state automatically. If you cannot use it, manually call CakeGeneratorFactory::clearInstances() and BaseFactory::resetDefaultGenerator() between tests.

Faker library is not installed

Faker library is not installed. Please install it using: `composer require --dev fakerphp/faker`

Cause: the default generator is faker, but the package isn't installed.

Fix: either install Faker (composer require --dev fakerphp/faker) or switch the generator type:

Configure::write('FixtureFactories.generatorType', 'dummy');

See Generators for the comparison.

DummyGenerator library is not installed

Same shape as the Faker error. Install with composer require --dev johnykvsky/dummygenerator (requires PHP 8.3+) or switch back to 'faker'.

Method works on one generator, not the other

Most methods are shimmed for compatibility, but a handful differ. Check the method compatibility table before using a generator-specific method.

Test data leaks between tests

Symptoms: prior test's Authors rows show up in the next test's queries.

Cause: no fixture strategy, or TruncateStrategy is failing silently because of FK constraints.

Fix: use FactoryTransactionStrategy. It rolls back via transaction so FKs never fight you, and it captures non-factory writes too.

Validation errors when persisting

Factories deactivate validation by default. If you're seeing rule/validation failures from persist(), something is overriding that — check whether you've set $marshallerOptions or $saveOptions on the factory.

To re-enable validation deliberately:

protected array $marshallerOptions = ['validate' => true];
protected array $saveOptions = ['checkRules' => true];

Schema is out of date

Symptoms: missing columns, SQLSTATE[42S22], etc.

Fix: run your migrations against the test DB. With the CakePHP Migrations plugin, the Migrator tool keeps the test schema in sync automatically.

If you've manually edited an already-applied migration file, the test DB still has the old schema and migrations won't re-run that file. Wipe and re-migrate:

# Provided by the Setup plugin (dereuromark/cakephp-setup)
bin/cake db wipe -c test
bin/cake migrations migrate -c test

Without the Setup plugin, drop the test database manually (or empty it via your DB client) and re-run migrations. See dereuromark/cakephp-setup for the db wipe command.

Bake doesn't generate what I expected

The bake command uses defaultDataMap and columnPatterns to choose generator methods per column. If a column is filled with the wrong helper, teach the bake command via configuration:

'columnPatterns' => [
    '/^phone/' => '$generator->phoneNumber()',
    '/^zip/'   => '$generator->postcode()',
],

Then re-run bin/cake bake fixture_factory <Model> --force.

setGenerator() affects unrelated factories

By default, setGenerator() changes the global default — any subsequent factory uses the new generator too. To scope it to one factory instance:

Configure::write('FixtureFactories.instanceLevelGenerator', true);

See Fixture Factories — instance-level generators for details.