barryvdh/laravel-ide-helper · error · RuntimeException

Cannot generate Eloquent helper

Error message

Cannot generate Eloquent helper

What it means

ide-helper:eloquent builds an Alias for the root class Illuminate\Database\Eloquent\Model and renders `eloquent()` helper methods into the generated file (src/Generator.php:91-115). Before rendering, Alias::detectRoot() must confirm the root class actually exists; if `$this->root` stays null (or resolves to a trait) the alias is marked invalid and Generator throws this RuntimeException (src/Generator.php:97-99). In practice it means the Eloquent Model class could not be loaded in the current environment, usually a broken or incomplete vendor tree rather than an ide-helper misconfiguration.

Source

Thrown at src/Generator.php:98

    {
        $app = app();
        return $this->view->make('ide-helper::helper')
            ->with('namespaces_by_extends_ns', $this->getAliasesByExtendsNamespace())
            ->with('namespaces_by_alias_ns', $this->getAliasesByAliasNamespace())
            ->with('real_time_facades', $this->getRealTimeFacades())
            ->with('helpers', $this->detectHelpers())
            ->with('include_fluent', $this->config->get('ide-helper.include_fluent', true))
            ->render();
    }

    public function generateEloquent()
    {
        $name = 'Eloquent';
        $facade = Model::class;
        $magicMethods = array_key_exists($name, $this->magic) ? $this->magic[$name] : [];
        $alias = new Alias($this->config, $name, $facade, $magicMethods, $this->interfaces);
        if (!$alias->isValid()) {
            throw new \RuntimeException('Cannot generate Eloquent helper');
        }

        //Add extra methods, from other classes (magic static calls)
        if (array_key_exists($name, $this->extra)) {
            $alias->addClass($this->extra[$name]);
        }

        $app = app();
        return $this->view->make('ide-helper::helper')
            ->with('namespaces_by_extends_ns', [])
            ->with('namespaces_by_alias_ns', ['__root' => [$alias]])
            ->with('real_time_facades', [])
            ->with('helpers', '')
            ->with('include_fluent', false)
            ->with('factories', [])
            ->render();
    }

View on GitHub (pinned to 3a886dca5c)

Solutions

1. Run `composer install` from the directory containing composer.lock so vendor/ is complete, then retry `php artisan ide-helper:eloquent`.
2. If Eloquent is genuinely absent, install it: `composer require illuminate/database` (or use a full `laravel/framework` application), matching the version of your other illuminate components.
3. Run `composer dump-autoload -o` to rebuild the class map when the package is present but not loadable.
4. If you do not need Eloquent helpers, drop the dedicated eloquent invocation and rely on `ide-helper:generate` alone.

Example fix

# before: micro-app without Eloquent
$ composer remove illuminate/database
$ php artisan ide-helper:eloquent
RuntimeException: Cannot generate Eloquent helper

# after
$ composer require illuminate/database
$ php artisan ide-helper:eloquent
A new helper file was written to _ide_helper.php

// Gate the command on Eloquent actually being loadable
if (!class_exists(\Illuminate\Database\Eloquent\Model::class)) {
    fwrite(STDERR, "illuminate/database not installed; skipping ide-helper:eloquent\n");
    return 1;
}

try {
    \Artisan::call('ide-helper:eloquent');
} catch (\RuntimeException $e) {
    if (str_contains($e->getMessage(), 'Cannot generate Eloquent helper')) {
        // vendor tree incomplete or Eloquent absent; run composer install and retry
        report($e);
    } else {
        throw $e;
    }
}

When it happens

Trigger: Running `php artisan ide-helper:eloquent` (or generating `ide-helper` with eloquent enabled) in an environment where class_exists('Illuminate\Database\Eloquent\Model') is false: illuminate/database not installed (custom micro-app using only container/support components), a truncated or partially updated vendor directory, a stale optimized autoloader after upgrading laravel/framework, or running the command from a bootstrap that never registers the composer autoloader.

Common situations: Micro-services or test harnesses built on illuminate/components without Eloquent; CI images where `composer install` used --no-dev or a filtered vendor list; a git merge or partial deploy that left vendor/ half-written; local copy of the repo used outside a full Laravel application.

Related errors

• Class '$class' not found.
• Error resolving relation model of %s:%s() : %s
• Your IDE helper model hook must implement Barryvdh\LaravelId
• Cannot load template for {name}: {message}

AI-assisted analysis of barryvdh/laravel-ide-helper@3a886dca5c (2026-08-23). Data as JSON: /api/errors/93565af3aa099121. Report an issue: GitHub.