Troubleshooting

Troubleshooting

Cache Missing

Error:

FixtureKit::CacheMissingError

Meaning: cache file was not generated before mount.

Checks:

• Fixture was declared in that context/class.
• Framework entrypoint is required (fixture_kit/rspec or fixture_kit/minitest).
• Cache path is writable.

Fixture Definition Not Found

Error:

FixtureKit::FixtureDefinitionNotFound

Checks:

• File exists at <fixture_path>/<name>.rb.
• File returns FixtureKit.define { ... }.

Multiple Fixture Declarations

Error:

FixtureKit::MultipleFixtures

Meaning: same context/class declared fixture more than once.

Fix: keep one declaration per context/class; use nested scope/class override instead.

Invalid Declaration

Error:

FixtureKit::InvalidFixtureDeclaration

Checks:

• Provide exactly one of name or block.

Foreign Key Violations

Error:

FixtureKit::Error: Foreign key violations found in cached fixture data.
The cache may be stale relative to your current schema or fixture definitions.

Meaning: after replaying cached INSERTs, FixtureKit ran connection.check_all_foreign_keys_valid! and the database reported violations. Verification is gated by ActiveRecord.verify_foreign_keys_for_fixtures (default true since Rails 8.0 load_defaults) and supported on PostgreSQL and SQLite.

Most likely causes:

• Fixture cache was generated against an older schema; an FK column or referenced table has since changed.
• A fixture definition references records that no longer exist after recent edits.

Fix: clear the cache and let it regenerate.

rm -rf tmp/cache/fixture_kit
bundle exec rspec

If you don't want this verification, set ActiveRecord.verify_foreign_keys_for_fixtures = false in your test config.

Runner Started Twice

Error:

FixtureKit::RunnerAlreadyStartedError

Meaning: internal startup invoked more than once in same runner instance.

Fix: avoid manually calling FixtureKit.runner.start in tests that already use entrypoints.

Verify Callback Wiring

Use temporary logging:

FixtureKit.configure do |config|
  config.on_cache_save { |fixture| puts "save: #{fixture.identifier} (#{fixture.path})" }
  config.on_cache_saved { |fixture, duration| puts "saved: #{fixture.identifier} in #{duration}" }
  config.on_cache_mount { |fixture| puts "mount: #{fixture.identifier}" }
  config.on_cache_mounted { |fixture, duration| puts "mounted: #{fixture.identifier} in #{duration}" }
end