`Term::fromModel()` fails with `Call to a member function sites() on null` due to `Blink::once()` race condition

[BartWaardenburg]

Bug description

When using the Eloquent driver for both taxonomies and terms, API requests to /api/taxonomies/{handle}/terms fail with:

Call to a member function sites() on null

The error occurs in src/Taxonomies/Term.php:152 in the defaultLocale() method.

How to reproduce

1. Configure Statamic to use Eloquent driver for:

   • taxonomies
   • terms
   • sites

2. Seed taxonomy terms to the database using dataForLocale('default', [...])

3. Make an API request to /api/taxonomies/organization_types/terms

4. The request fails with the error above

Root cause analysis

The issue is in Term::fromModel() in the eloquent-driver (vendor/statamic/eloquent-driver/src/Taxonomies/Term.php:26):

$term = (new static)
    ->slug($model->slug)
    ->taxonomy($model->taxonomy)  // Sets taxonomy handle as string
    ->model($model)
    ->blueprint($model->data['blueprint'] ?? null);

collect($data['localizations'] ?? [])
    ->except($term->defaultLocale())  // <-- Calls taxonomy()->sites()->first()

When defaultLocale() is called, it invokes $this->taxonomy() (the getter), which does:

->getter(function ($taxonomy) {
    return $taxonomy ? Blink::once("taxonomy-{$taxonomy}", function () use ($taxonomy) {
        return Taxonomy::findByHandle($taxonomy);
    }) : null;
})

The problem: Due to timing issues in the request lifecycle, Blink::once() can cache null even when the taxonomy exists in the database. Once null is cached, subsequent calls return null, causing ->sites() to fail.

Evidence from debugging

• Warming the Blink cache with Blink::put("taxonomy-{$handle}", $taxonomy) in middleware before the controller runs does NOT fix the issue
• The cache shows has('taxonomy-organization_types') = true both before AND after the controller fails with 500
• Taxonomy::all() and Taxonomy::findByHandle() work correctly in isolation (e.g., in tinker)
• The issue only manifests during web API requests with the Eloquent driver

Workaround

We implemented a middleware that intercepts /api/taxonomies/{handle}/terms requests and queries the database directly, bypassing Term::fromModel() entirely:

$terms = DB::table('taxonomy_terms')
    ->where('taxonomy', $taxonomyHandle)
    ->where('site', 'default')
    ->get();

Versions

Software	Version
Statamic	5.x (latest)
Laravel	11.x
Eloquent Driver	latest
PHP	8.3

[duncanmcclean]

Are you able to provide the full output of php please support:details?

[BartWaardenburg]

Environment
Application Name: Statamic CMS
Laravel Version: 12.44.0
PHP Version: 8.3.29
Composer Version: 2.9.3
Environment: local
Debug Mode: ENABLED
URL: localhost:8000
Maintenance Mode: OFF
Timezone: UTC
Locale: en

Cache
Config: NOT CACHED
Events: NOT CACHED
Routes: NOT CACHED
Views: NOT CACHED

Drivers
Broadcasting: log
Cache: database
Database: sqlite
Logs: stack / single
Mail: log
Queue: database
Session: database

Storage
public/storage: LINKED

Locales
Installed: en
LaravelLang\Lang\Plugin: 15.26.3
Locales Version: 2.10.0
Protected: en
Publisher Version: 16.7.0

Sentry
Enabled: MISSING DSN
Environment: local
Laravel SDK Version: 4.20.0
PHP SDK Version: 4.19.1
Release: NOT SET
Sample Rate Errors: 100%
Sample Rate Performance Monitoring: 100%
Sample Rate Profiling: NOT SET
Send Default PII: DISABLED

Statamic
Addons: 2
Sites: 1
Stache Watcher: Enabled (auto)
Static Caching: Disabled
Version: 5.70.0 PRO

Statamic Addons
statamic/eloquent-driver: 4.35.2
statamic/seo-pro: 6.11.5

Statamic Eloquent Driver
Asset Containers: eloquent
Assets: eloquent
Blueprints: file
Collection Trees: eloquent
Collections: file
Entries: eloquent
Fieldsets: file
Form Submissions: eloquent
Forms: file
Global Sets: file
Global Variables: eloquent
Navigation Trees: eloquent
Navigations: file
Revisions: file
Sites: eloquent
Taxonomies: eloquent
Terms: eloquent
Tokens: eloquent

[ryanmitchell]

I've taken a look into this and after some code diving I'm struggling to see the issue (or indeed how it can be an issue). Would you be able to either:

1. Supply a failing test demonstrating the issue
   or
2. Provide a basic repo with steps on how to reproduce the issue?

[BartWaardenburg]

@ryanmitchell I've done extensive debugging on this issue and can now explain exactly what's happening.

The Root Cause

There are actually two related issues that combine to cause this bug:

Issue 1: TaxonomyRepository::findByHandle() caches null without forgetting

In TermRepository::find(), when the result is null, the blink key is forgotten:

$term = Blink::once($blinkKey, function () { ... });

if (! $term) {
    Blink::forget($blinkKey);  // ✅ Forgets null result
    return null;
}

But in TaxonomyRepository::findByHandle(), this pattern is missing:

$taxonomyModel = Blink::once("eloquent-taxonomies-{$handle}", function () use ($handle) {
    return app('statamic.eloquent.taxonomies.model')::whereHandle($handle)->first();
});

return $taxonomyModel instanceof Model ? ... : null;  // ❌ No Blink::forget() when null

Issue 2: The taxonomy column isn't always selected

When the Statamic API is called with a fields parameter (e.g., ?fields=id,slug,title), only those specific columns are selected from the database. The taxonomy column is not included, causing $model->taxonomy to be NULL.

When Term::fromModel($model) is called with a null taxonomy, the Statamic core's taxonomy() getter caches null via Blink::once("taxonomy-{$taxonomy}", ...). Later, when ->in($site) is called (in TermQueryBuilder::transform()), it triggers inDefaultLocale() → defaultLocale() → $this->taxonomy()->sites()->first(), which fails because taxonomy() returns the cached null.

How to Reproduce

// This simulates what happens when fields parameter excludes 'taxonomy'
$model = TermModel::where('taxonomy', 'my_taxonomy')->select(['id', 'slug', 'data'])->first();
echo $model->taxonomy;  // NULL - because 'taxonomy' wasn't selected!

Then call Term::fromModel($model) and the error occurs.

My Workaround

For now, I've removed the fields and limit parameters from my API calls, which avoids triggering the bug since all columns are selected by default.

Proposed Fix for eloquent-driver

Three changes are needed:

1. TaxonomyRepository::findByHandle() - forget null cache (consistency with TermRepository)

public function findByHandle($handle): ?TaxonomyContract
{
    $blinkKey = "eloquent-taxonomies-{$handle}";

    $taxonomyModel = Blink::once($blinkKey, function () use ($handle) {
        return app('statamic.eloquent.taxonomies.model')::whereHandle($handle)->first();
    });

    if (! $taxonomyModel instanceof Model) {
        Blink::forget($blinkKey);
        return null;
    }

    return app(TaxonomyContract::class)->fromModel($taxonomyModel);
}

2. Term::fromModel() - pre-warm the core Blink cache

public static function fromModel(Model $model)
{
    $data = $model->data;

    // Pre-warm the core Blink cache to prevent null caching issues
    $taxonomy = Taxonomy::findByHandle($model->taxonomy);
    if ($taxonomy) {
        Blink::put("taxonomy-{$model->taxonomy}", $taxonomy);
    }

    // ... rest of method
}

3. TermQueryBuilder::get() and paginate() - ensure taxonomy is always selected

public function get($columns = ['*'])
{
    // Ensure 'taxonomy' is always selected as it's required for Term::fromModel()
    if (! in_array('*', $columns) && ! in_array('taxonomy', $columns)) {
        $columns[] = 'taxonomy';
    }
    
    // ... rest of method
}

I can submit a PR with these fixes if you'd like.

[ryanmitchell]

@BartWaardenburg thanks for digging in and proposing solutions. 1 and 3 both seem fine to me so feel free to open a PR. 2 wont be necessary once the others are in place.

[ryanmitchell]

Closed by #534