halo-dev/halo · error · ServerWebInputException

Unable to complete the request because the theme configMapNa

Error message

Unable to complete the request because the theme configMapName is blank.

What it means

updateThemeJsonConfig() fetches the Theme resource by name and reads theme.spec.configMapName before upserting JSON config. If configMapName is blank (null, empty, or whitespace), there is no ConfigMap to write settings into, so a ServerWebInputException (HTTP 400) is thrown. A theme only has a configMapName when it ships a settings definition.

Source

Thrown at application/src/main/java/run/halo/app/theme/endpoint/ThemeEndpoint.java:290

                                .response(responseBuilder().implementation(Object.class)))
                .build();
    }

    private Mono<ServerResponse> fetchThemeJsonConfig(ServerRequest request) {
        return themeNameInPathVariableOrActivated(request)
                .flatMap(themeName -> client.fetch(Theme.class, themeName))
                .mapNotNull(theme -> theme.getSpec().getConfigMapName())
                .flatMap(settingConfigService::fetchConfig)
                .flatMap(json -> ServerResponse.ok().bodyValue(json));
    }

    private Mono<ServerResponse> updateThemeJsonConfig(ServerRequest request) {
        final var themeName = request.pathVariable("name");
        return client.fetch(Theme.class, themeName)
                .doOnNext(theme -> {
                    String configMapName = theme.getSpec().getConfigMapName();
                    if (StringUtils.isBlank(configMapName)) {
                        throw new ServerWebInputException(
                                "Unable to complete the request because the theme configMapName is blank.");
                    }
                })
                .flatMap(theme -> {
                    final var configMapName = theme.getSpec().getConfigMapName();
                    return request.bodyToMono(ObjectNode.class)
                            .switchIfEmpty(Mono.error(new ServerWebInputException("Required request body is missing")))
                            .flatMap(
                                    configJsonData -> settingConfigService.upsertConfig(configMapName, configJsonData));
                })
                .then(ServerResponse.noContent().build());
    }

    private Mono<ServerResponse> invalidateCache(ServerRequest request) {
        final var name = request.pathVariable("name");
        return client.get(Theme.class, name)
                .flatMap(theme -> templateEngineManager.clearCache(name))
                .then(ServerResponse.noContent().build());

View on GitHub (pinned to d2f5165f9c)

Solutions

Confirm the theme actually provides a settings form (theme.yaml spec.settingName and spec.configMapName). If not, there is nothing to configure; do not call the config update endpoint.
Reinstall or reload the theme so the configMapName/settings are provisioned.
If the theme is meant to have settings, fix its theme.yaml to include settingName/configMapName and reload.
Check the Theme CR in the cluster: kubectl get theme <name> -o yaml and verify spec.configMapName.

Defensive patterns

Strategy: validation

Validate before calling

// Validate the Theme has a configMapName before calling the update endpoint:
Theme theme = client.fetch(Theme.class, name).block();
if (theme == null || StringUtils.isBlank(theme.getSpec().getConfigMapName())) {
    throw new IllegalStateException("Theme '" + name + "' has no configMapName; cannot update config.");
}

Try / catch

// In the handler, map the 400 to a user-friendly message:
.onErrorResume(ServerWebInputException.class, e ->
    ServerResponse.badRequest().bodyValue(Map.of(
        "message", "This theme has no settings form (configMapName is blank).")))

Prevention

Only expose the config-update UI for themes whose spec.configMapName is non-blank.
Ensure themes declare settingName/configMapName in theme.yaml before install.
Reload themes after editing their manifest so settings plumbing is provisioned.
Unit-test the endpoint against a theme with no settings to confirm the 400 contract.

When it happens

Trigger: Calling PUT /apis/api.console.halo.run/v1alpha1/themes/{name}/config (the theme JSON config update endpoint) for a Theme whose spec.configMapName was never set, e.g. a theme installed without a settings.yaml, or a manually-created Theme resource missing the configMapName/spec.settingName pair.

Common situations: Installing a theme that declares no settings form; a theme manifest whose spec omits configMapName; the ConfigMap was deleted out-of-band; editing a theme CR directly without the settings plumbing.

Related errors

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