getgrav/grav · error · RuntimeException

__METHOD__(): You need to pass option 'directory'

Error message

__METHOD__(): You need to pass option 'directory'

What it means

FlexDirectoryForm::instance() is a factory for directory-level (object-less) Flex forms; it requires an option named 'directory' holding a FlexDirectory instance. Omitting the option (or misspelling it) throws immediately with HTTP code 400. This is an API-contract error made by the calling code, not a runtime state problem.

Source

Thrown at system/src/Grav/Framework/Flex/FlexDirectoryForm.php:72

    /**
     * @param array $options    Options to initialize the form instance:
     *                          (string) name: Form name, allows you to use custom form.
     *                          (string) unique_id: Unique id for this form instance.
     *                          (array) form: Custom form fields.
     *                          (FlexDirectory) directory: Flex Directory, mandatory.
     *
     * @return FlexFormInterface
     */
    public static function instance(array $options = []): FlexFormInterface
    {
        if (isset($options['directory'])) {
            $directory = $options['directory'];
            if (!$directory instanceof FlexDirectory) {
                throw new RuntimeException(__METHOD__ . "(): 'directory' should be instance of FlexDirectory", 400);
            }
            unset($options['directory']);
        } else {
            throw new RuntimeException(__METHOD__ . "(): You need to pass option 'directory'", 400);
        }

        $name = $options['name'] ?? '';

        return $directory->getDirectoryForm($name, $options);
    }

    /**
     * FlexForm constructor.
     * @param string $name
     * @param FlexDirectory $directory
     * @param array|null $options
     */
    public function __construct(string $name, FlexDirectory $directory, ?array $options = null)
    {
        $this->name = $name;
        $this->setDirectory($directory);
        $this->setName($directory->getFlexType(), $name);

View on GitHub (pinned to 6040efed04)

Solutions

1. Resolve the directory first and pass it: $directory = $grav['flex']->getDirectory('your-type'); FlexDirectoryForm::instance(['directory' => $directory, 'name' => 'your-form']);
2. If you only have the type string, verify getDirectory() did not return null (unknown flex type) before calling instance().
3. Pass the FlexDirectory object itself, never the type string.
4. If you actually want an object form, use FlexForm::instance() with 'object' or 'directory'+'key'.

Example fix

// before
$form = FlexDirectoryForm::instance(['name' => 'login']);

// after
$flex = Grav::instance()['flex'];
$form = FlexDirectoryForm::instance([
    'directory' => $flex->getDirectory('login'),
    'name' => 'login',
]);

// Resolve and verify the directory before calling the factory
$flex = \Grav\Common\Grav::instance()['flex'];
$directory = $flex ? $flex->getDirectory($type) : null;
if (!$directory instanceof \Grav\Framework\Flex\FlexDirectory) {
    throw new \InvalidArgumentException("Unknown flex directory '{$type}'");
}
$form = FlexDirectoryForm::instance(['directory' => $directory, 'name' => $name]);

function isFlexDirectory(mixed $value): bool
{
    return $value instanceof \Grav\Framework\Flex\FlexDirectory;
}

When it happens

Trigger: Calling FlexDirectoryForm::instance(['name' => 'login']) with no 'directory' key; passing 'directory' => 'grav-login' (a string) is caught by the sibling check, but omitting it entirely hits this line; typos like 'dir' or 'flex_directory'.

Common situations: Custom plugin code building a directory form for the first time; upgrading code that previously constructed FlexDirectoryForm via new and was refactored to the instance() factory; copying example code for FlexForm (object forms) and forgetting directory forms always need 'directory'.

Related errors

• __METHOD__(): 'object' should be instance of FlexObjectInter
• __METHOD__(): 'directory' should be instance of FlexDirector
• __METHOD__(): You need to pass option 'directory' or 'object
• Flash has no directory
• Flash has no object

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