halo-dev/halo · error · IllegalArgumentException

The metadata.generateName must not be blank when metadata.na

Error message

The metadata.generateName must not be blank when metadata.name is blank

What it means

Thrown as an IllegalArgumentException from ReactiveExtensionClientImpl.create when an Extension's metadata has neither a non-blank name nor a non-blank generateName. Halo requires at least one: a concrete name, or a generateName prefix it can append a random suffix to. With both blank it cannot form a unique store name.

Source

Thrown at application/src/main/java/run/halo/app/extension/ReactiveExtensionClientImpl.java:242

    }

    @Override
    public Mono<JsonExtension> getJsonExtension(GroupVersionKind gvk, String name) {
        return fetchJsonExtension(gvk, name).switchIfEmpty(Mono.error(() -> new ExtensionNotFoundException(gvk, name)));
    }

    @Override
    public <E extends Extension> Mono<E> create(E extension) {
        return Mono.fromCallable(() -> {
                    var metadata = extension.getMetadata();
                    // those fields should be managed by halo.
                    metadata.setCreationTimestamp(Instant.now());
                    metadata.setDeletionTimestamp(null);
                    metadata.setVersion(null);

                    if (!hasText(metadata.getName())) {
                        if (!hasText(metadata.getGenerateName())) {
                            throw new IllegalArgumentException(
                                    "The metadata.generateName must not be blank when metadata.name is " + "blank");
                        }

                        // generate name with random text
                        metadata.setName(metadata.getGenerateName()
                                + secure().nextAlphanumeric(GENERATE_NAME_RANDOM_LENGTH)
                                        // Prevent data conflicts caused by database case sensitivity
                                        .toLowerCase());
                    }
                    extension.setMetadata(metadata);
                    return converter.convertTo(extension);
                })
                .subscribeOn(this.scheduler)
                // the method secureStrong() may invoke blocking SecureRandom, so we need to subscribe
                // on boundedElastic thread pool.
                .flatMap(extStore -> doCreate(extension, extStore.getName(), extStore.getData()))
                .flatMap(created -> Mono.fromCallable(() -> {
                            watchers.onAdd(convertToRealExtension(created));

View on GitHub (pinned to d2f5165f9c)

Solutions

1. Set metadata.name to a concrete DNS-subdomain-safe value before create, OR set metadata.generateName to a prefix so Halo appends a random suffix.
2. Always attach a Metadata object to the Extension before calling create.
3. If auto-naming is desired, use generateName (e.g. 'my-resource-') and read back the assigned name from the returned object.

Example fix

// before:
//   var ext = new MyExtension();
//   ext.setMetadata(new Metadata()); // both name and generateName blank
//   client.create(ext);
// after:
//   var meta = new Metadata();
//   meta.setGenerateName("my-resource-");
//   ext.setMetadata(meta);
//   client.create(ext);

// ensure name or generateName is set before create
Metadata meta = extension.getMetadata();
if (meta == null) {
    meta = new Metadata();
    extension.setMetadata(meta);
}
if (!StringUtils.hasText(meta.getName())
    && !StringUtils.hasText(meta.getGenerateName())) {
    meta.setGenerateName("res-"); // or set a concrete name
}

When it happens

Trigger: client.create(extension) where extension.getMetadata() has name blank AND generateName blank — e.g. a freshly constructed Extension with an empty/absent Metadata, or a Metadata where both fields were explicitly cleared.

Common situations: Developer builds an Extension and forgets to set Metadata or its name/generateName; plugin constructs a resource expecting auto-naming but did not set generateName; copy of a template object whose metadata was stripped; null metadata.

Related errors

• Unexpected APIVersion string: {}
• Failed to validate {gvk}
• Invalid attachment
• User permissions not set in PermissionUtils
• ESM provider manifest must be an object.

AI-assisted analysis of halo-dev/halo@d2f5165f9c (2026-08-14). Data as JSON: /api/errors/a016ef356970723b. Report an issue: GitHub.