Apache Camel 4.x Upgrade Guide

The library used for Camel Grok component has been migrated from no more maintained io.krakens:java-grok to its fork io.github.whatap:java-grok. It implies small differences listed here.

The camel-api module now has an optional dependency on org.jspecify:jspecify for null safety annotations (@NullMarked, @Nullable). The dependency is <optional>true</optional>, so it is not pulled transitively into your application. The annotations are used to document nullability contracts across the Camel API surface and enable compile-time null checking with tools like NullAway. If you want to leverage these annotations in your own code or tooling, add org.jspecify:jspecify explicitly to your project dependencies.

The org.apache.camel.support.DefaultHeaderFilterStrategy changed default setting for lowercase from false to true.

The type converters for Java serialized objects with types java.io.ObjectInput and java.io.ObjectOutput has been removed. Java object serialization is a recurring source of security issues and therefore these converters has been removed. These converters are not used at all by Camel itself. To restore compatibility then end users can add these type converters back as custom converters in their own Camel applications. However, using Java serialization is discouraged and highly recommend to use other means.

Removed org.apache.camel.spi.ReifierStrategy which is no longer in use by Camel and can safely be removed.

A new getChildren() default method has been added to org.apache.camel.NamedNode. It returns List<NamedNode> and provides a uniform API for traversing the route model tree, including structural nodes like WhenDefinition and OtherwiseDefinition that are not ProcessorDefinition subclasses and therefore invisible to getOutputs(). Code that walks the model tree recursively should prefer getChildren() over getOutputs() to avoid needing special-case handling for Choice EIP.

The NamedNode.getLevel() and getParentId() methods no longer treat when and otherwise nodes as "shallow". Previously these nodes were flattened to the same level as their parent choice, which was inconsistent with how doCatch and doFinally work inside doTry. Now when and otherwise contribute their own level, consistent with the tree structure exposed by getChildren(). This affects level values reported via JMX (ManagedProcessor.getLevel()) and dev consoles for nodes inside Choice EIP branches.

The camel wrapper command now installs the scripts as camel instead of camelw. You can use the --command-name=camelw to use the old name.

When camel.main.routesReloadEnabled=true (automatically set by camel run --dev), Camel now auto-disables contentCache on resource-based components (such as xslt) whose default is true, so that edits to the resource file are picked up on the next message without restarting the route. Set camel.component.<name>.contentCache=true (or pass ?contentCache=true on the URI) to opt back in to caching during dev mode.

A new canonical JSON Schema variant (camelYamlDsl-canonical.json) has been added alongside the existing classic schema (camelYamlDsl.json). The canonical schema removes all implicit patterns (string shorthands, inline expressions, oneOf/anyOf/not constructs) to provide a simpler, more predictable schema for tooling such as IDEs, code generators, and AI assistants. See the YAML DSL documentation for details.

The YamlValidator class now accepts a boolean canonical constructor parameter to validate against the canonical schema.

A new camel yaml normalize command has been added to Camel JBang. It rewrites YAML routes from the classic (shorthand) form to the canonical (explicit) form. The camel validate yaml command also supports a new --canonical flag to validate against the canonical schema.

When using camel-kafka-starter with Spring Boot, the standard spring.kafka. properties are now automatically bridged to the Camel Kafka component configuration (CAMEL-22760). This means you no longer need to duplicate Kafka settings under both spring.kafka. and camel.component.kafka.*.

The bridged properties include bootstrap-servers, security.protocol, SSL/TLS settings (keystore, truststore), consumer.group-id, client-id, and SASL properties (sasl.mechanism, sasl.jaas.config, sasl.kerberos.service.name).

Explicit camel.component.kafka.* settings always take precedence over the bridged Spring Boot values.

The bridge is enabled by default. To disable it, set:

The default ObjectInputFilter pattern that ships with the components listed below has been tightened to explicitly deny classes under java.net. before allowing the rest of java., javax. and org.apache.camel.. The previous default did not deny java.net.**, which meant classes whose hashCode/equals methods perform network I/O (notably java.net.URL and java.net.InetAddress) could be deserialized by the in-code default.

Affected components:

The new default is:

(or !java.net.;java.;org.apache.camel.;!* for the aggregation repository components, which do not include javax.).

The endpoint-level option deserializationFilter and the JVM-wide system property -Djdk.serialFilter continue to override this default. Applications that have a legitimate need to deserialize java.net.URL or other java.net.* types must configure an explicit filter.

For production deployments handling untrusted serialized payloads, the in-code filter is intended as defense-in-depth only. The primary mitigation should be configured at the messaging provider:

JMS ObjectMessage support is now disabled by default. Java object serialization is a recurring source of security issues, and Camel JMS routes rarely use ObjectMessage in practice. The component will now refuse to create or read jakarta.jms.ObjectMessage instances unless the new objectMessageEnabled option is explicitly set to true.

This affects the following endpoint/component options that rely on ObjectMessage internally:

To restore the previous behavior, enable the option at the component or endpoint level:

Or, on a single endpoint:

The same default applies to camel-sjms (and camel-sjms2, which inherits from it): JMS ObjectMessage support is now disabled by default and gated by a new objectMessageEnabled option (default false) on SjmsComponent / SjmsEndpoint.

This affects the same endpoint/component options as camel-jms:

To restore the previous behavior, enable the option at the component or endpoint level:

Or, on a single endpoint:

Hazelcast instances created and managed by Camel (when no user-supplied Config or HazelcastInstance is provided) now apply a default JavaSerializationFilterConfig on the SerializationConfig of the Config built by Camel. The default whitelists the class name prefixes java., javax., org.apache.camel. and blacklists java.net..

This affects:

A user-supplied JavaSerializationFilterConfig (set on the SerializationConfig of a Config provided via hazelcastConfigUri, a referenced Config bean, or already wired into a pre-built HazelcastInstance) is respected and is not overwritten.

Applications that store classes outside the default whitelist on a Hazelcast topic, queue, map, list, set, or in one of the repositories above must provide their own Config with a JavaSerializationFilterConfig configured for their class names.

Camel stomp was deprecated with Camel 4.17. The stomp library didn’t have any activities in the last 10 years. The component is now removed.

Camel AWS X-Ray was deprecated with Camel 4.17. Amazon Web Services X-Ray service is in maintenance mode since February 2026. The component is now removed.

Camel Guava EventBus was deprecated with Camel 4.6. The component is now removed.

Camel Grape was deprecated with Camel 4.1. The component is now removed.

Camel Grape was deprecated with Camel 4.0. The component is now removed.

In order to prevent some potential span leakage in camel-opentelemetry2 (see notes below) we had to perform some changes and introduce the following parameter:

This is required in order to distinguish the older traceProcessors parameter which now accounts exclusively for custom processors. Keeping the default parameter (false) could increase the number of spans generated, though, this is required to guarantee consistency and memory sealing. If you need to reduce the number of spans for any reason you can explicitly provide exclusion configuration.

In this version we have also changed certain interfaces, so, if you have custom telemetry implementations, you may need to adjust to them:

In order to prevent a potential leak when running asynchronous components we need to rethink the implementation details of camel-opentelemetry2 and remove the Scope wrapping that, when asynchronous, was opening the Scope in a thread and closing in another (what we had called "dirty" context). We are now removing this wrapping and moving this part exclusively in the custom Camel Processors. Here Camel will take care to open the Opentelemetry scope and close it within the same thread.

What it means is that, from now on, the final user or any third party dependency can only "control" the Opentelemetry context within the boundary of a Processor execution.

This is just an informative note, there is not action expected by the final user.

The applyGuardrail producer operation now reads the guardrail identifier from a new dedicated header CamelAwsBedrockGuardrailIdentifier (constant BedrockConstants.GUARDRAIL_IDENTIFIER, typed String) instead of CamelAwsBedrockGuardrailConfig. The CamelAwsBedrockGuardrailConfig header is typed GuardrailConfiguration and is reserved for the converse and converseStream operations; the previous code path silently produced null whenever a route mixed converse and applyGuardrail calls. If you were not setting the guardrail identifier via header, the endpoint-level guardrailIdentifier option continues to work without changes.

The Exchange header constants in JGroupsConstants have been renamed to follow the Camel naming convention used across the rest of the component catalog. The Java field names are unchanged; only the header string values have changed:

Routes that reference the constant symbolically (for example setHeader(JGroupsConstants.HEADER_JGROUPS_DEST, …​)) continue to work without changes. Routes that set the header by its literal string value (for example setHeader("JGROUPS_DEST", …​)) must be updated to use the new value (setHeader("CamelJGroupsDest", …​)).

The Exchange header constants in ElasticSearchRestClientConstant have been renamed to follow the Camel naming convention used across the rest of the component catalog. The Java field names are unchanged; only the header string values have changed:

Routes that reference the constant symbolically (for example setHeader(ElasticSearchRestClientConstant.SEARCH_QUERY, …​)) continue to work without changes. Routes that set the header by its literal string value (for example setHeader("SEARCH_QUERY", …​)) must be updated to use the new value (setHeader("CamelElasticsearchSearchQuery", …​)).

The listObjects operation now uses the ListObjectsV2 AWS API instead of the deprecated ListObjects API. If you use pojoRequest=true with operation=listObjects, you must change your request and response types:

The non-POJO path (header-based configuration) is updated automatically and requires no changes.

Fixed the JetStream consumer pull subscription mode (which is the default) so that messages are actually consumed from the server. Previously the consumer would set up a pull subscription but never issue any pull/fetch requests, so no messages were delivered until the user explicitly switched to push mode with pullSubscription=false.

Two new endpoint options have been added to control the pull fetch loop:

The Exchange header values exposed by LuceneConstants have been renamed to follow the standard Camel naming convention. The field names are unchanged, so routes referencing the constants (LuceneConstants.HEADER_QUERY, LuceneConstants.HEADER_RETURN_LUCENE_DOCS) continue to work without modification. However, routes that set or read these headers using the raw string values must be updated:

As a consequence, the generated Endpoint DSL header accessors on LuceneHeaderNameBuilder have been renamed accordingly:

The Exchange header constants in JGroupsRaftConstants have been renamed to follow the Camel naming convention used across the rest of the component catalog. The Java field names are unchanged; only the header string values have changed:

Routes that reference the constant symbolically (for example setHeader(JGroupsRaftConstants.HEADER_JGROUPSRAFT_SET_TIMEOUT, …​)) continue to work without changes. Routes that set the header by its literal string value (for example setHeader("JGROUPSRAFT_SET_TIMEOUT", …​)) must be updated to use the new value (setHeader("CamelJGroupsRaftSetTimeout", …​)).

The component camel-ironmq is deprecated. The official library used has been unmaintained since 2017 All the other client libraries (in other languages) are unmaintained since the same amount of time. The whole iron-io GitHub organization has almost no activity.

The component camel-digitalocean is deprecated. The java library used has been unmaintained for several years and there is no replacement.

The component camel-irc is deprecated. The library used had no stable release since 2007. There is no Java library very active for this protocol.

The component camel-iec-60870 is deprecated. The library used to implement it NeoScada is no more maintained since 2021. There are no alternatives in Java with compatible license.