Apache Camel 4.x Upgrade Guide

This document is for helping you upgrade your Apache Camel application from Camel 4.x to 4.y. For example, if you are upgrading Camel 4.0 to 4.2, then you should follow the guides from both 4.0 to 4.1 and 4.1 to 4.2.

The Camel Upgrade Recipes project provides automated assistance for some common migration tasks. Note that manual migration is still required. See the documentation page for details.

Upgrading Camel 4.20 to 4.21

camel-core

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.

camel-yaml-dsl

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.

camel-kafka / Spring Boot

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:

camel.component.kafka.bridge-spring-kafka-properties=false

Default deserialization filter tightened

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:

  • camel-jms, camel-sjms, camel-amqp, camel-mina, camel-netty, camel-netty-http, camel-vertx-http, camel-infinispan

  • The aggregation repository components: camel-leveldb, camel-cassandraql, camel-consul, camel-sql (JDBC aggregation repository)

The new default is:

!java.net.**;java.**;javax.**;org.apache.camel.**;!*

(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:

  • ActiveMQ Artemis: deserializationAllowList / deserializationDenyList (see the Artemis docs)

  • ActiveMQ Classic: the org.apache.activemq.SERIALIZABLE_PACKAGES system property

camel-jms

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:

  • jmsMessageType=Object (or sending a Serializable body that is auto-detected as Object)

  • transferExchange=true

  • transferException=true

  • receiving a JMS ObjectMessage produced by an external sender

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

camel.component.jms.objectMessageEnabled=true

Or, on a single endpoint:

jms:queue:foo?objectMessageEnabled=true

camel-stomp removal

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-xray removal

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-telemetry

If you have custom telemetry implementations, the following interfaces have changed:

org.apache.camel.telemetry.SpanLifecycleManager

The create method signature has changed:

// Old signature
Span create(String spanName, Span parent, SpanContextPropagationExtractor extractor)

// New signature
Span create(String spanName, String spanKind, Span parent, SpanContextPropagationExtractor
extractor)

org.apache.camel.telemetry.SpanDecorator

A new method must be implemented:

String getSpanKind(String operation)

This method should return the appropriate SpanKind based on the operation. Most implementations can extend from:

  • AbstractSpanDecorator (returns INTERNAL for all operations)

  • AbstractHttpSpanDecorator (returns CLIENT for EVENT_SENT, SERVER for EVENT_RECEIVED)

  • AbstractMessagingSpanDecorator (returns PRODUCER for EVENT_SENT, CONSUMER for EVENT_RECEIVED)

Back to top