filamentphp/filament · error · InvalidArgumentException

Block of class [$blockClass] must have a unique name, passed

Error message

Block of class [$blockClass] must have a unique name, passed to the [make()] method.

What it means

Builder blocks are identified by name — it becomes the block type key stored in the builder's JSON state. `Block::make()` falls back to `getDefaultName()` (null on the base class) and throws an InvalidArgumentException when the resolved name is blank, before the block can be registered in a `Builder` schema.

Source

Thrown at packages/forms/src/Components/Builder/Block.php:38

    use HasName;

    protected string | BackedEnum | Htmlable | Closure | null $icon = null;

    protected int | Closure | null $maxItems = null;

    final public function __construct(string $name)
    {
        $this->name($name);
    }

    public static function make(?string $name = null): static
    {
        $blockClass = static::class;

        $name ??= static::getDefaultName();

        if (blank($name)) {
            throw new InvalidArgumentException("Block of class [$blockClass] must have a unique name, passed to the [make()] method.");
        }

        $static = app($blockClass, ['name' => $name]);
        $static->configure();

        return $static;
    }

    public static function getDefaultName(): ?string
    {
        return null;
    }

    public function icon(string | BackedEnum | Htmlable | Closure | null $icon): static
    {
        $this->icon = $icon;

        return $this;

View on GitHub (pinned to 53483fa934)

Solutions

Pass an explicit unique name: `Block::make('hero')`.
In custom block classes, override `getDefaultName()` to return a stable non-blank identifier.
Guard dynamic registration: skip or default blocks whose configured key is blank.

Example fix

// before
Builder::make('content')->blocks([
    Block::make()->schema([...]),
]);

// after
Builder::make('content')->blocks([
    HeroBlock::make('hero')->schema([...]),
]);

Defensive patterns

Strategy: type-guard

Validate before calling

foreach ($blockConfigs as $key => $config) {
    if (blank($key)) {
        continue;
    }

    $blocks[] = $blockClass::make($key)->schema($config['schema'] ?? []);
}

Type guard

function assertBlockName(?string $name): string
{
    if (blank($name)) {
        throw new InvalidArgumentException('Builder block name cannot be blank.');
    }

    return $name;
}

// Block::make(assertBlockName($key))

Prevention

Override getDefaultName() in reusable block classes with a stable identifier.
Treat blank keys in plugin config arrays as configuration errors and validate them at load time.
Block names become JSON keys — keep them stable to avoid orphaned content.

When it happens

Trigger: `Block::make()` with no argument in a block class that does not override `getDefaultName()`, or `Block::make($key)` where `$key` is null/empty when the builder schema is constructed.

Common situations: Custom block classes where the author assumed auto-naming, registering blocks from a plugin config array with a missing key, or copy-pasted blocks with the name removed.

Related errors

AI-assisted analysis of filamentphp/filament@53483fa934 (2026-08-17). Data as JSON: /api/errors/1982eece720d19e4. Report an issue: GitHub.