barryvdh/laravel-ide-helper · warning

Cannot load template for {name}: {message}

Error message

Cannot load template for {name}: {message}

What it means

While generating the PhpStorm meta file, ide-helper:meta loads static templates (auth, configs, middleware, routes, views, translations) from the package's php-templates/ directory via requireOnce (src/Console/MetaCommand.php:326-340). Any Throwable raised while including the template file is caught and downgraded to this console warning, and the template is replaced with an empty collection. It is a warning, not an abort: the meta file is still written, but the affected expectedArguments set will be empty, so PhpStorm loses completion for that group.

Source

Thrown at src/Console/MetaCommand.php:336

                'class' => '\Illuminate\Support\Env',
                'method' => 'get',
                'argumentSet' => 'env',
            ],
        ];
    }

    /**
     * @return Collection
     */
    protected function loadTemplate($name)
    {
        if (!isset($this->templateCache[$name])) {
            $file =  __DIR__ . '/../../php-templates/' . basename($name) . '.php';
            try {
                $value = $this->files->requireOnce($file) ?: [];
            } catch (\Throwable $e) {
                $value = [];
                $this->warn('Cannot load template for ' . $name . ': ' . $e->getMessage());
            }

            if (!$value instanceof Collection) {
                $value = collect($value);
            }
            $this->templateCache[$name] = $value;
        }

        return $this->templateCache[$name];
    }

    /**
     * Get the console command options.
     *
     * @return array
     */
    protected function getOptions()
    {

View on GitHub (pinned to 3a886dca5c)

Solutions

1. Check the embedded message: 'file does not exist' points at a missing template file; another message points at a failure inside the template's own code.
2. Restore the package intact: `composer reinstall barryvdh/laravel-ide-helper` (Composer >= 2.4), or delete vendor/barryvdh and rerun `composer install`.
3. Verify the folder exists and is readable: `ls vendor/barryvdh/laravel-ide-helper/php-templates/` should list auth.php, configs.php, middleware.php, routes.php, views.php, translations.php.
4. If you forked or patched the package, make sure every loadTemplate('...') name maps to an existing php-templates/{name}.php file.
5. Rerun `php artisan ide-helper:meta` and confirm the warning is gone and the meta file contains the expectedArguments entries.

Example fix

# before
$ php artisan ide-helper:meta
Cannot load template for routes: The file "/app/vendor/barryvdh/laravel-ide-helper/php-templates/routes.php" does not exist

# after: restore the pruned vendor files
$ composer reinstall barryvdh/laravel-ide-helper
$ php artisan ide-helper:meta
A new meta file was written to .phpstorm.meta.php

// Verify the shipped templates exist before generating meta
$tplDir = dirname(\Composer\InstalledVersions::getInstallPath('barryvdh/laravel-ide-helper')) . '/laravel-ide-helper/php-templates';
foreach (['auth', 'configs', 'middleware', 'routes', 'views', 'translations'] as $name) {
    if (!is_file("{$tplDir}/{$name}.php")) {
        fwrite(STDERR, "Missing ide-helper template: {$name}\n");
        exit(1);
    }
}

When it happens

Trigger: The template file `php-templates/{name}.php` does not exist under the installed package (Illuminate's Filesystem::requireOnce throws FileNotFoundException), the vendor directory is partially copied or a file was stripped by a deployment filter, or the template file itself throws at include time (parse-level issue after a bad patch, or an artisan call inside the template failing in an exotic environment).

Common situations: Docker images or PHAR bundlers that prune vendor/ and accidentally drop the php-templates folder; a partially completed `composer update` interrupted mid-write; custom forks of the package where a template was renamed; running generation on a mount where file permissions block reading the template.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Class '$class' not found.
• Your IDE helper model hook must implement Barryvdh\LaravelId
• Cannot generate Eloquent helper
• Error resolving relation model of %s:%s() : %s

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