getgrav/grav · error · BadMethodCallException

Cache folder not defined.

Error message

Cache folder not defined.

What it means

CompiledBase is the parent of CompiledConfig, CompiledBlueprints and CompiledLanguages — the classes that compile and cache Grav's YAML configuration into PHP files. Its constructor requires a non-empty $cacheFolder (normally resolved from the cache:// stream, e.g. cache://compiled/config) and throws BadMethodCallException if it is empty. An empty folder means the resource locator could not resolve the cache stream to a real path, so there is nowhere to write the compiled file.

Source

Thrown at system/src/Grav/Common/Config/CompiledBase.php:61

    /** @var array  List of files to load. */
    protected $files;

    /** @var string */
    protected $path;

    /** @var mixed  Configuration object. */
    protected $object;

    /**
     * @param  string $cacheFolder  Cache folder to be used.
     * @param  array  $files  List of files as returned from ConfigFileFinder class.
     * @param string $path  Base path for the file list.
     * @throws BadMethodCallException
     */
    public function __construct($cacheFolder, array $files, $path)
    {
        if (!$cacheFolder) {
            throw new BadMethodCallException('Cache folder not defined.');
        }

        $this->path = $path ? rtrim($path, '\\/') . '/' : '';
        $this->cacheFolder = $cacheFolder;
        $this->files = $files;
    }

    /**
     * Get filename for the compiled PHP file.
     *
     * @param string|null $name
     * @return $this
     */
    public function name($name = null)
    {
        if (!$this->name) {
            $this->name = $name ?: md5(json_encode(array_keys($this->files)));
        }

View on GitHub (pinned to 6040efed04)

Solutions

1. Resolve the folder from the locator and check it before constructing: $cache = $grav['locator']->findResource('cache://compiled/config', true, true); if (!$cache) fail with context
2. Verify the cache stream in streams.schemes and that the cache/ directory exists and is writable by the web user
3. Clear the compiled caches (rm -rf cache/*) after fixing stream config so stale state does not persist
4. For custom compiled classes, default the folder to a known path like GRAV_ROOT . '/cache/compiled' when the stream lookup fails intentionally

Example fix

// before
$compiled = new CompiledConfig($cache, $files, GRAV_ROOT); // $cache === false cast to ''

// after
$cache = $locator->findResource('cache://compiled/config', true, true);
if (!$cache) {
    throw new RuntimeException('cache:// stream could not be resolved; check streams config and cache dir permissions');
}
$compiled = new CompiledConfig($cache, $files, GRAV_ROOT);

$cache = $grav['locator']->findResource('cache://compiled/config', true, true);
if (!$cache) {
    throw new RuntimeException('cache:// stream unresolvable — check streams.schemes and cache dir permissions');
}
$compiled = new CompiledConfig($cache, $files, GRAV_ROOT);

try {
    $compiled = new CompiledConfig($cache, $files, GRAV_ROOT);
} catch (BadMethodCallException $e) {
    // cacheFolder came back empty — the locator could not resolve cache://
    throw new RuntimeException('Compiled config needs a resolvable cache folder: ' . $e->getMessage(), 0, $e);
}

When it happens

Trigger: Constructing new CompiledConfig('', $files, $path) (or the blueprints/languages siblings) with an empty folder; the locator returning false from findResource('cache://compiled/config', true, true) because the cache stream or its target directory is broken; a plugin building one of these classes without resolving the stream first.

Common situations: streams.schemes cache entry misconfigured or removed in user/config; the cache directory cannot be created due to permissions so findResource fails; a custom or environment-specific setup (multi-site) where cache:// points at an invalid path; code that assumes the stream always resolves.

Related errors

• At least one cache must be specified
• No backups defined...
• Backup location: {$backup_root} does not exist...
• Setup: Configuration reload loop detected!
• Configuration is missing streams.schemes!

AI-assisted analysis of getgrav/grav@6040efed04 (2026-08-17). Data as JSON: /api/errors/7c36acd044376a67. Report an issue: GitHub.