quarkusio/quarkus · error · ConfigurationException

The 'quarkus.hibernate-orm.mapping.format.global' configurat

Error message

The 'quarkus.hibernate-orm.mapping.format.global' configuration property is deprecated and only accepts 'ignore'. Quarkus no longer pre-builds format mappers. Either define a custom `FormatMapper` bean or let Hibernate ORM create its own internally. Refer to https://quarkus.io/guides/hibernate-orm#json_xml_serialization_deserialization for guidance. Remove this property or set it to 'ignore'.

What it means

BuiltinFormatMapperBehaviour.FAIL's action calls fail(), which throws a ConfigurationException. Since Quarkus no longer pre-builds JSON/XML FormatMapper instances for Hibernate ORM, the only accepted value of quarkus.hibernate-orm.mapping.format.global is 'ignore'; any other value (the old 'fail' behavior) deliberately aborts startup with this message.

Source

Thrown at extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/customized/BuiltinFormatMapperBehaviour.java:42

        @Override
        public void action() {
            fail();
        }
    },
    /**
     * A no longer supported option. Using it will result in the application failing at build time.
     *
     * @asciidoclet
     */
    FAIL {
        @Override
        public void action() {
            fail();
        }
    };

    private static void fail() {
        throw new ConfigurationException(
                "The 'quarkus.hibernate-orm.mapping.format.global' configuration property is deprecated"
                        + " and only accepts 'ignore'. Quarkus no longer pre-builds format mappers."
                        + " Either define a custom `FormatMapper` bean or let Hibernate ORM create its own internally."
                        + " Refer to https://quarkus.io/guides/hibernate-orm#json_xml_serialization_deserialization for guidance."
                        + " Remove this property or set it to 'ignore'.");
    }

    public abstract void action();
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Remove the quarkus.hibernate-orm.mapping.format.global property from your configuration entirely.
2. Or set quarkus.hibernate-orm.mapping.format.global=ignore, the only accepted value.
3. If you need custom JSON/XML mapping, define your own FormatMapper CDI bean instead of relying on built-in mapper configuration.
4. See the referenced Quarkus Hibernate ORM guide section on JSON/XML serialization for the supported approach.

Example fix

# before
quarkus.hibernate-orm.mapping.format.global=fail

# after
quarkus.hibernate-orm.mapping.format.global=ignore

// Detect the deprecated/unsupported property value before startup
String val = System.getProperty("quarkus.hibernate-orm.mapping.format.global",
        System.getenv().getOrDefault("QUARKUS_HIBERNATE_ORM_MAPPING_FORMAT_GLOBAL", ""));
if (!val.isEmpty() && !val.equals("ignore")) {
    throw new IllegalStateException(
        "quarkus.hibernate-orm.mapping.format.global must be removed or set to 'ignore'; got: " + val);
}

try {
    startApplication();
} catch (io.quarkus.runtime.ConfigurationException e) {
    if (e.getMessage() != null && e.getMessage().contains("mapping.format.global")) {
        log.error("Remove the property or set it to 'ignore'; use a custom FormatMapper bean if needed", e);
    }
    throw e;
}

When it happens

Trigger: Keeping quarkus.hibernate-orm.mapping.format.global=fail (or any value other than 'ignore') in application.properties after upgrading Quarkus, causing Hibernate ORM startup to throw a ConfigurationException.

Common situations: Upgrading an application from an older Quarkus where this property controlled built-in mapper behavior; stale config in CI/test profiles; following outdated documentation or examples.

Related errors

• Weigher class '<className>' must implement com.github.benman
• Invalid ORM compatibility version: %1$s. Valid versions are:
• The class (${name}) cannot be created during deployment.
• Can not add converter ${converter.name()} that is not parame
• Converter ${converter.name()} must be parameterized with a s

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/3fc8f9fc2687d10e. Report an issue: GitHub.