Apache Camel 4.x Upgrade Guide

The Camel JBang CLI (Camel CLI) and TUI have been promoted from Preview to Stable support level. The MCP Server has also been promoted to Stable.

The Camel JBang CLI now automatic resolves quarkus version to use, instead of hardcoded 3.33.1.1 (https://github.com/apache/camel/commit/d1f4713ebdf787ab04a31c50a6f07e3ca66f0c2b).

The camel cmd route-diagram and camel cmd route-topology now accept one or more Camel route source files (instead of only the name/pid of a running integration), so diagrams and inter-route topology can be generated at design/source time without starting the application first, for example:

route-diagram previously only accepted a single source file; both commands now accept a set of files. route-topology previously required a running integration and printed "No running Camel integration found" when none matched; it now falls back to loading the given files the same way route-diagram already did.

As part of this, camel.main.dumpRoutes=json (used internally by these commands, and available to users dumping route structure to a folder) now additionally writes a route-topology.json file alongside the per-route structure files when topology dumping is enabled (the default). This file is now always written, with empty nodes/edges arrays if there are no routes to connect, so its presence reliably signals that the dump has completed (previously it was silently skipped when there were no routes).

The Camel TUI (camel tui) accepts --theme=dark or --theme=light to choose the color palette at startup. When omitted, the persisted camel.tui.theme value from .camel-cli.properties is used.

The Camel TUI now has a Settings…​ entry in the F2 actions menu for choosing the theme, the starting tab, and the default run-from-folder. These are stored under camel.tui.* keys (camel.tui.theme, camel.tui.startTab, camel.tui.defaultFolder) in the Camel CLI configuration file. Each key is read from and written back to the file where it currently lives: a key present in the local ./camel-cli.properties stays local (project override), while every other key defaults to the global ~/.camel-cli.properties.

The Camel TUI (camel tui) theme is now backed by CSS stylesheets and ships a switchable light/dark palette. Press F4 to toggle at runtime; the selection is persisted as camel.tui.theme in .camel-cli.properties.

The Camel CLI user configuration file has been renamed from camel-jbang-user.properties to camel-cli.properties (global ~/.camel-cli.properties, local ./camel-cli.properties). The dot convention is unchanged: the global file is a hidden dotfile, the local file is visible. On first run the CLI automatically renames a pre-existing global ~/.camel-jbang-user.properties to ~/.camel-cli.properties and a pre-existing local ./camel-jbang-user.properties to ./camel-cli.properties; an existing new file is never overwritten.

The Agent.chat() method return type has changed from String to Result<String> (from dev.langchain4j.service.Result). This allows the agent producer to expose token usage (input, output, total token count) and finish reason as exchange headers, consistent with the chat, tools, and embeddings components.

If you have a custom Agent implementation, update the chat method signature:

The helper classes OpenAiChatLanguageModelBuilder and HugginFaceChatLanguageModelBuilder have been removed. They were not wired into the component; the chatModel is autowired instead.

If you used these helpers directly, configure your ChatModel with LangChain4j’s own builders or Spring Boot starters and inject it into the component. === camel-openai

The conversationMemory feature on the chat-completion operation has two behavior fixes:

The Throughput attribute on the ManagedPerformanceCounter JMX MBean now reports an EWMA (exponentially weighted moving average) value with a 1-minute decay window, instead of the previous raw instantaneous rate. This produces a smoother, more stable reading that converges to the true average throughput rather than oscillating between zero and spike values.

If you have tooling that consumes the JMX throughput value and expects the old instantaneous behavior, be aware that the reported value will now ramp up and decay gradually.

When consuming from Azure Service Bus in PEEK_LOCK mode with maxAutoLockRenewDuration > 0, Camel now actively renews message locks using a dedicated ServiceBusReceiverAsyncClient and Camel’s internal PeriodTaskScheduler. This addresses a limitation where the Azure SDK’s built-in lock renewal is tied to the processMessage callback duration, which returns immediately for asynchronous Camel routes — causing long-running exchanges to silently lose their message locks.

The new behavior activates automatically when all of the following are true:

No configuration changes are required. The existing maxAutoLockRenewDuration option controls how long Camel will continue renewing a message’s lock.

The camel-debezium component has upgraded from Debezium 3.5.2 to 3.6.0.

The following 10 Oracle connector options have been removed by Debezium 3.6.0 and are no longer available:

If you use any of these options, remove them from your configuration as they will cause errors.

Due to new requirements from Apache Fory, when using Apache Fory Dataformat, the JVM parameter --add-opens java.base/java.lang.invoke=ALL-UNNAMED must be provided.

The pqc data format now encrypts the message payload with authenticated encryption (AEAD) instead of the previous unauthenticated ECB mode. 128-bit block ciphers are encrypted with GCM and the ChaCha20 stream cipher is encrypted with ChaCha20-Poly1305, so both the confidentiality and the integrity of the data are now protected, and tampered or corrupted messages are detected and rejected on decryption.

As a consequence:

The preSort option on the File, FTP, FTPS, SFTP, Azure Files, and SMB consumers has changed from a boolean to a String. Previously, preSort=true sorted files by name only. The option now supports the following values:

The pre-sort is applied on the raw file listing before any filtering or eager limiting, which makes it possible to combine preSort=modified with eagerMaxMessagesPerPoll=true and maxMessagesPerPoll=10 to efficiently consume the 10 oldest files without creating Exchange objects for every file on the server.

The forceWrites producer option on the File endpoint has been deprecated. This option has had no effect since Camel 2.20, when the file-writing implementation was refactored to use java.nio.file.Files.move() and Files.copy() instead of FileChannel-based streaming. The forceWrites flag was intended to call FileChannel.force(true) (fsync) after writing, but no write path has invoked it for several major versions.

The default value has been changed from true to false to reflect the actual behavior. The option will be removed in a future release.

When unmarshalling a MIME message with headersInline=true, the mime-multipart data format now applies a HeaderFilterStrategy to the headers copied from the MIME content onto the Camel message. Camel-internal headers (the Camel* namespace, matched case-insensitively) present in the external MIME headers are no longer copied onto the message, consistent with the inbound header filtering already performed by the camel-mail consumer.

Ordinary application headers are unaffected. If a route relied on Camel* headers being propagated from the MIME content, set them explicitly after unmarshalling.

When consuming a CloudEvent in structured content mode (application/cloudevents+json), the Knative component now applies a HeaderFilterStrategy to the event fields (extensions) mapped from the payload onto the Camel message. Camel-internal headers (the Camel* namespace, matched case-insensitively) present as structured-event fields are no longer mapped onto the message, consistent with the inbound header filtering already performed on the binary content-mode / HTTP header path.

Ordinary CloudEvent extension attributes are unaffected. If a route relied on Camel*-named fields being propagated from the structured payload, set them explicitly after consuming the event.

When consuming a message with preserveHeaders=true, the IronMQ consumer now applies a HeaderFilterStrategy to the header entries embedded in the JSON message envelope before mapping them onto the Camel message. Camel-internal headers (the Camel* namespace, matched case-insensitively) present in the envelope are no longer mapped onto the message, consistent with the inbound header filtering performed by other consumers.

Ordinary application headers are unaffected. If a route relied on Camel* headers being propagated from the message envelope, set them explicitly after consuming the message.

The tls endpoint option now correctly documents its default as false (previously the catalog listed the default as true, but the runtime value was always false). No behavioral change — the runtime default was already false.

When authenticationEnabled=true but neither a basic-auth properties file (basicPropertiesFile) nor a JWT keystore (jwtKeystoreType) is configured, Camel now behaves differently under the prod profile (camel.main.profile=prod).

Under the prod profile, startup now fails instead of starting the embedded HTTP server without authentication. Under the dev profile and with no profile configured, the existing warning-only behavior is retained for backward compatibility.

The metadataMaxAgeMs (metadata.max.age.ms) option was incorrectly labeled as producer-only, but is applied to both consumer and producer Kafka clients. The label has been corrected to common.

If you use the Endpoint DSL, the metadataMaxAgeMs method has moved from the producer (advanced) builder to the common builder.

When saslAuthType is set, the generated JAAS configuration and additional SASL properties are now applied using putIfAbsent semantics, so explicitly configured saslJaasConfig, callback handler classes, or token endpoint URLs take precedence over the auto-generated values.

For OAuth (saslAuthType=OAUTH), the JAAS string now contains only login-module parameters (clientId, clientSecret, scope). The oauth.token.endpoint.uri and callback handler class are set as separate Kafka client properties instead of being embedded in the JAAS string, matching the Kafka client’s expected configuration format.

For Kerberos (saslAuthType=KERBEROS), if the principal is not configured, the configurer now assumes an external JAAS configuration (e.g. via java.security.auth.login.config) and skips JAAS string generation instead of throwing an exception. This supports deployment scenarios where Kerberos is configured externally.

With useIterator=true, the Kafka producer splits an Iterable body into one record per element. A Jackson JsonNode implements Iterable, so a scalar value node (e.g. an IntNode produced by transform().jq(".my-value")) was seen as an empty iterable and produced no record, silently discarding the message with no exception or log.

Scalar value nodes are now sent as a single record. Only container nodes (ArrayNode, ObjectNode) are still split, which is unchanged. Any convertBodyTo(…​) previously used as a workaround is no longer required.

Setting sslEndpointAlgorithm to none or false now correctly disables SSL hostname verification by setting ssl.endpoint.identification.algorithm to an empty string. Previously the property was simply omitted, which caused Kafka clients to fall back to their default (https), leaving hostname verification silently enabled.

When no groupId is configured, the auto-generated UUID is now shared across all consumer threads (consumersCount). Previously each thread received its own random UUID, causing each thread to independently consume all partitions, which resulted in every message being processed consumersCount times.

The batch producer (when the body is a List) now respects the endpoint-configured key option for elements that do not have a CamelKafkaKey header. Previously, elements without the header would get a null record key even when key=fixedKey was configured on the endpoint. Additionally, plain list elements (not Exchange or Message) are now properly converted to the configured serializer type.

The queueBufferingMaxMessages producer option has been deprecated. This option has had no effect since the old Scala Kafka producer was removed in Camel 2.17 (CAMEL-9467). Use bufferMemorySize or maxBlockMs instead.

When using allowManualCommit=true together with a DefaultKafkaManualCommitFactory or DefaultKafkaManualAsyncCommitFactory, the framework previously auto-committed offsets for every processed record — even when the route did not call KafkaManualCommit.commit(). This defeated the purpose of manual commit mode and could cause message loss.

The framework no longer auto-commits offsets after processing each partition when manual commit is enabled. Offsets are only committed when the route explicitly calls KafkaManualCommit.commit() on the exchange header. The configured factory still controls whether that explicit commit executes synchronously or asynchronously.

The camel catalog commands (camel catalog component, camel catalog dataformat, camel catalog language, camel catalog transformer, camel catalog kamelet, …​) now size the DESCRIPTION column to the detected terminal width instead of the previous fixed 80-character cap, so wide terminals show more of the description before it is truncated with an ellipsis. The NAME column width is also standardized across these commands (it previously differed per command, for example 60 for transformer and 30 elsewhere).

Terminal width is now detected on Windows (cmd / PowerShell) via mode con, in addition to the existing COLUMNS / stty size detection. When no terminal can be detected (for example when the output is piped or redirected), the width falls back to 120 columns. For full, untruncated output suitable for scripting, use the --json option.

The camel infra list table now sizes its DESCRIPTION column to the terminal width, and truncates the IMPLEMENTATION and SERVICE_DATA columns with an ellipsis instead of letting the raw service data overflow the terminal. The complete, structured service data remains available via --json.

The Kinesis consumer with a configured shardId previously called the DescribeStream API on every poll cycle to locate the shard, risking AWS rate limits (10 TPS per account) and failing for streams with more than 100 shards (no pagination). The consumer now uses the same cached shard list from the ShardMonitor background thread that the multi-shard path already uses. The ShardMonitor uses the ListShards API (paginated, 100 TPS limit) and now paginates through all pages, supporting streams with any number of shards.

This is a transparent performance improvement with no configuration changes required.

The batch producer (body is an Iterable) previously applied a single CamelAwsKinesisPartitionKey header to all records, routing them all to the same shard. A new CamelAwsKinesisPartitionKeys header (List<String>) is now supported: when set, each record in the batch is assigned the partition key at the corresponding index. If the list has fewer entries than records, the remaining records fall back to the single CamelAwsKinesisPartitionKey header. The existing single-key behavior is unchanged when the new header is not set.

When fileDir is configured, the Azure Storage Blob and DataLake consumers now ensure the downloaded local file stays within the configured directory, so a remote object name containing ../ sequences can no longer resolve to a path outside it. This is consistent with the containment already performed by the file-based consumers (see the localWorkDirectory note in the 4.21 upgrade guide).

Ordinary object names are unaffected. A name that resolves outside fileDir is now rejected with an IllegalArgumentException.

The Weaviate Java client has been upgraded from v5 (io.weaviate:client) to v6 (io.weaviate:client6). This is a major upgrade with several breaking changes.

The following configuration properties are now bound as java.time.Duration instead of raw milliseconds (long/int):

Plain numeric values in application.properties/application.yaml are still interpreted as milliseconds, so existing configurations keep working unchanged. In addition, readable duration values such as 5s or 2m are now supported.

This is a source-incompatible change for code that reads these values programmatically: the getters and setters of SupervisingRouteControllerConfiguration and CamelStartupConditionConfigurationProperties now use java.time.Duration instead of long/int.

The clustered route controller property camel.clustered.controller.initial-delay is unchanged: it keeps its String type because it supports Camel time patterns (for example 10 seconds) that Duration binding does not.

The replyTimeout option on the component level has been fixed to default to 30 seconds, aligning it with the endpoint-level default that was documented since Camel 3.20.7 / 3.21. Previously, the component-level default was still 5 seconds, which would override the endpoint’s declared 30-second default. If you were relying on the effective 5-second timeout, you can restore it by explicitly setting replyTimeout=5000 on the component or endpoint.

The queue durable default has been changed from false to true when using autoDeclare. This aligns queues with the exchange default (which was already durable=true) and with RabbitMQ 4.3+ which no longer permits non-durable, non-exclusive queues by default (the transient_nonexcl_queues deprecated feature is now denied by default).

If you were relying on non-durable queues, you can restore the previous behavior by explicitly setting arg.queue.durable=false&arg.queue.exclusive=true on the endpoint URI. Note that RabbitMQ 4.3+ requires non-durable queues to also be exclusive.

The Multicast EIP now correctly honors UseOriginalAggregationStrategy, consistent with the Splitter and Recipient List EIPs. Previously, Multicast did not bind the original exchange on the strategy, so the strategy was silently ineffective — especially in error scenarios where the aggregated result could overwrite the original exchange body instead of preserving it.

PostgresAggregationRepository and ClusteredPostgresAggregationRepository were broken since Camel 3.4: every insert failed with a parameter-index error because the version column was bound but not included in the generated INSERT …​ ON CONFLICT DO NOTHING statement. Both repositories now include the version column in the insert, and the clustered variant also writes the instance_id column to the completed table when recoveryByInstance is enabled (previously instance-scoped recovery could never match any row).

The aggregation tables used with these repositories must have the version BIGINT column, as already required by JdbcAggregationRepository for reading and updating aggregates. When recoveryByInstance is enabled, the completed table must have the instance_id VARCHAR(255) column as documented.

The sign, verify, hybridSign and hybridVerify operations previously encoded a String message body using the JVM default charset (String.getBytes()). The default charset is platform dependent, so signing on one JVM and verifying on another with a different default could disagree on the bytes of a non-ASCII payload and make verification fail.

String bodies are now always encoded as UTF-8. On Java 18 and newer the default charset is already UTF-8 (JEP 400), so this is a no-op there; on Java 17 with a non-UTF-8 default, the signature of a non-ASCII String payload changes. Binary bodies (byte[], InputStream) are unaffected, as they are signed byte-for-byte. === camel-sql - Schema-qualified aggregation repository names

The table-name validation in JdbcAggregationRepository now accepts schema-qualified names such as myschema.aggregation. Previously the validation regex only allowed simple identifiers ([a-zA-Z_][a-zA-Z0-9_]*), rejecting any name containing a dot. Names starting with a digit, containing spaces, or with multiple dots (e.g. catalog.schema.table) are still rejected.

The remove() method in JdbcAggregationRepository and ClusteredJdbcAggregationRepository now throws OptimisticLockingException when it detects a stale version during the delete. Previously a stale remove was silently treated as successful. If your error handling or aggregation strategy catches specific exception types around remove(), you may need to account for OptimisticLockingException.

The TemplateParser now catches TokenMgrError (a JavaCC lexer error) and wraps it in ParseRuntimeException. Previously a malformed stored-procedure template with characters outside the token alphabet would propagate as a raw java.lang.Error.

The CloudTrail consumer previously kept its lookup cursor in a static field (shared across all cloudtrail consumers in the JVM), issued a single non-paginated LookupEvents call with a default maxResults of 1, and advanced the cursor by the newest event time plus one second. As a result it could silently drop events. The consumer now keeps the cursor per-endpoint, paginates through every page of the window, and de-duplicates events by id at the window boundary.

Two behavior changes follow:

Custom KinesisResumeAction subclasses registered in the Camel registry under the CamelKinesisDbResumeAction key must now provide a public no-arg constructor. The consumer creates a separate instance per shard via reflection to avoid concurrent mutation when multiple shards are processed in parallel. Per-shard state (builder, shardId, streamName) is injected via setters after construction. Any initialization that was previously done in a parameterized constructor should be moved to setters or to the evalEntry method.

The SQS producer no longer sets per-message DelaySeconds when delayQueue=true (delay is queue-level) or when the queue is FIFO (AWS rejects per-message delay with InvalidParameterValue). Previously the CamelAwsSqsDelayHeader header was applied unconditionally, which could cause AWS errors on FIFO queues and was redundant on delay queues. If your route relied on per-message delay overrides on a delay queue, the override will now be silently ignored.

The secureProcessing option (default true) is now applied to the Saxon TransformerFactory unconditionally. Previously it was only set when saxonExtensionFunctions was configured, meaning the default configuration silently ran without FEATURE_SECURE_PROCESSING.

Additionally, the Saxon factory now sets ACCESS_EXTERNAL_DTD and ACCESS_EXTERNAL_STYLESHEET to empty strings (matching the behavior of the plain xslt component), restricting stylesheet-driven external fetches.

Users of Saxon Professional or Enterprise editions who rely on Java extension functions called from XSLT stylesheets must now explicitly set secureProcessing=false on the endpoint.

The InMemorySagaCoordinator used for the Saga EIP (when no external LRA coordinator is configured) previously returned an already-completed future from compensate() and complete(), meaning the exchange finished before any compensation or completion endpoints had been invoked. Finalization failures were only logged as warnings and never propagated to the caller.

The coordinator now returns the actual finalization future, so the exchange waits for the compensation or completion callbacks to finish (including retries). If all retry attempts fail, the failure is propagated as an exception on the exchange, consistent with the camel-lra coordinator behavior.

This is a behavior change: routes that previously completed immediately regardless of compensation/completion outcome will now wait for finalization and may see exceptions that were previously swallowed. If your route relies on fire-and-forget saga finalization, consider using MANUAL completion mode instead.

The azure-eventhubs producer now applies a DefaultHeaderFilterStrategy to the headers copied onto EventData application properties. Camel-internal headers (the Camel* namespace, matched case-insensitively) are no longer forwarded to Azure Event Hubs, consistent with the inbound header filtering performed by other components.

Ordinary application headers are unaffected.

The getFile operation on the Data Lake consumer/producer now uses the standard client.openInputStream().getInputStream() instead of client.openQueryInputStream("SELECT * from BlobStorage"). The previous implementation relied on the Blob Query API, which had known issues requiring a SkipLastByteInputStream workaround. The SkipLastByteInputStream class in camel-util has been deprecated and will be removed in a future version.

The page-blob getRange calculation has been corrected from end - start to end - start + 1, since Azure page blob ranges are inclusive on both ends. If you had a workaround adjusting the range values to compensate for this off-by-one, it should be removed.

The @DataField.precision() attribute default has changed from 0 to -1 (meaning "unset"). Previously, a BigDecimal field without an explicit precision would throw ArithmeticException on unmarshal when the input had decimal places, and silently truncated decimals to zero on marshal. With this fix, omitting precision preserves the original scale from the input value.

The @DataField.rounding() attribute is now honored for BigDecimal fields that do not use a pattern. Previously it was only applied when a pattern was specified.

If you relied on the implicit precision=0 behavior to round BigDecimal values to integers, add precision = 0 explicitly to your @DataField annotation.

The transformerFactoryConfigurationStrategy option is now applied on all factory creation paths. Previously on xslt-saxon it was never invoked, and on plain xslt it was only invoked when transformerFactoryClass was explicitly set.