Apache Camel 4.x Upgrade Guide

The camel-reactive-executor-tomcat component has been deprecated. Its cross-thread ThreadLocal cleanup relied on reflective access to the private Thread.threadLocals field, which is denied by the JDK module system since JDK 17 and is incompatible with virtual threads. Without that cleanup, this executor is functionally identical to the built-in DefaultReactiveExecutor.

To migrate, remove the camel-reactive-executor-tomcat dependency from your project. Camel will automatically use the default reactive executor.

The Vert.x streamable transport now evicts orphaned MCP sessions automatically: keep-alive pings every 30 seconds (evict after consecutive failures on sessions with an open SSE stream) and an idle TTL of 5 minutes (evict sessions with no POST/GET activity). Configure with camel.server.mcp-session-keep-alive-interval and camel.server.mcp-session-idle-ttl; set either option to 0 to disable that mechanism.

CamelObjectInputStream (the shared stream used by Camel’s Java-object deserialization paths, such as the HTTP components) now installs a JEP-290 java.io.ObjectInputFilter while reading, as a defense-in-depth measure against unsafe deserialization. When no explicit filter pattern is supplied, the JVM-wide jdk.serialFilter is honoured if set, otherwise Camel’s default allow-list (DeserializationFilterHelper.DEFAULT_DESERIALIZATION_FILTER) is applied, which permits standard Java and Apache Camel types, denies java.net.**, and enforces graph-shape limits.

The built-in HTTP deserialization path already applied this filter, so most users are unaffected. Code that constructs CamelObjectInputStream directly and deserializes types outside the default allow-list must pass an explicit filter pattern to the new CamelObjectInputStream(InputStream, CamelContext, String) constructor (or configure jdk.serialFilter) to permit them.

Because the two-argument CamelObjectInputStream(InputStream, CamelContext) constructor now always installs a filter, calling setObjectInputFilter() on the resulting stream throws IllegalStateException ("filter can not be set more than once") on JDK 17+. Downstream code that previously constructed the stream and then set a filter separately should pass the pattern to the new CamelObjectInputStream(InputStream, CamelContext, String) constructor instead.

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 CLI and TUI AI prompt (camel ask, TUI F8 panel) now auto-detect Azure OpenAI when AZURE_OPENAI_API_KEY and AZURE_OPENAI_ENDPOINT are set (optional AZURE_OPENAI_DEPLOYMENT_NAME and AZURE_OPENAI_API_VERSION). Azure requests use the api-key header instead of Authorization: Bearer.

The Camel CLI and TUI AI prompt now support native Google Gemini when GEMINI_API_KEY is set (auto-detected before OpenAI). With --api-type=gemini, GOOGLE_API_KEY is also accepted. Gemini uses the generativelanguage.googleapis.com API with function-calling support. See Camel CLI - AI Tools for the full detection order.

camel run, camel dev, and camel debug accept --openapi-ui to expose Swagger UI for REST DSL OpenAPI at /q/openapi on the embedded HTTP server (OpenAPI JSON at /q/openapi.json by default). The feature is gated as developer-only (insecure:dev) via camel.jbang.openapiUi and camel.management.openapiUiEnabled. When --port is set without --management-port, the management server is co-bound to the same port so the UI and spec stay together. --openapi-ui also sets override properties for camel.rest.component=platform-http and camel.rest.apiContextPath=/q/openapi.json, which take precedence over values in application.properties or other property sources (same as other CLI -- server flags that use override properties).

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:

When RAG or tools are used, the agent producer also exposes CamelLangChain4jAgentSources (List<dev.langchain4j.rag.content.Content>) and CamelLangChain4jAgentToolExecutions (List<dev.langchain4j.service.tool.ToolExecution>) as exchange headers when present in the Result.

A new embeddingModel option has been added. It is autowired, so if an EmbeddingModel bean is present in the registry it will be automatically picked up. When set, ADD and SEARCH operations can accept plain text in the message body instead of requiring a pre-computed embedding in the CamelLangChain4jEmbeddingsEmbedding header. The header always takes precedence when present.

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.

The camel-langchain4j-tools component is deprecated. Use camel-ai-tool to define tools and camel-langchain4j-agent for tool-calling with LangChain4j models.

Migrate your tool definition routes from langchain4j-tools: to ai-tool::

Use langchain4j-agent with matching tags to invoke tools:

Add the camel-ai-tool dependency to your project:

The safeSearch endpoint option is now correctly propagated to the LangChain4j WebSearchRequest. Previously the option was accepted on the endpoint but ignored, so safeSearch=false still sent safeSearch=true to the search engine (the LangChain4j default).

The per-call token usage headers CamelOpenAIPromptTokens, CamelOpenAICompletionTokens, and CamelOpenAITotalTokens now declare javaType = Long in component metadata (previously Integer). The OpenAI SDK returns long values, so routes that read these headers with Integer.class should switch to Long.class.

Component metadata for exchange property CamelOpenAIResponse (storeFullResponse=true on chat-completion) now declares javaType = com.openai.models.chat.completions.ChatCompletion (previously com.openai.models.ChatCompletion). The runtime type was already the nested SDK class; update imports and exchange.getProperty(…​, ChatCompletion.class) references if your code still uses the old package name.

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 component-specific CredentialType enums, deprecated since Camel 4.19.0, have been removed in favor of the shared org.apache.camel.component.azure.common.CredentialType enum from camel-azure-common:

Endpoint URIs are unaffected: the credential type option values keep the same names. Java code that imports one of the removed enums — including typed Endpoint DSL calls such as credentialType(CredentialType) — must switch the import to org.apache.camel.component.azure.common.CredentialType.

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.

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 writeAsString option now correctly serializes single JSON object results (Maps) to a JSON String. Previously, a JsonPath expression evaluating to a JSON object (e.g. $.args) with writeAsString=true would return a java.util.Map with individually stringified values instead of a valid JSON String. If you were relying on the old behavior to split a Map result, change the expression to use a wildcard (e.g. $.content.* instead of $.content) to get a splittable list of JSON strings.

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 camel-xmpp component has upgraded Smack from 4.3.5 to 4.4.8. The smack-java7 module no longer exists in Smack 4.4 and has been replaced by smack-java8 (relevant if you declared it explicitly alongside camel-xmpp). When extracting headers from a stanza whose JiveProperties extension is not parsed by a registered provider, the unparsed extension is now represented by Smack’s StandardExtensionElement (the replacement for the removed DefaultExtensionElement); flat child elements are mapped to headers as before. See the Smack 4.4 readme for behavioral changes in the Smack library itself.

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 URI sanitization used for logs, JMX attributes, exception messages and the developer console (URISupport.sanitizeUri) now also redacts endpoint parameters whose name contains api-key (hyphenated) or authorization. Previously a credential supplied through a hyphenated or Authorization-style parameter/header name — for example additionalHeader.api-key=…​ (the Azure OpenAI auth header) or additionalHeader.Authorization=…​ in camel-openai — was written in clear text in sanitized URIs, even though the camelCase apiKey option was already redacted.

Because matching is a case-insensitive substring match, parameter names that merely contain authorization without being secrets — adjustAuthorization, jwtAuthorizationType, proxyAuthorizationPolicy — now also have their values shown as xxxxxx in sanitized URIs. This is a cosmetic change to sanitized output only and does not affect the actual endpoint configuration.

DefaultMaskingFormatter (used when logMask=true, and by tooling that reuses the same formatter) previously masked secrets only when a known sensitive key name appeared in key/value, XML or JSON text. Two credential shapes that have no such key are now also masked:

Helpers for these value shapes live on org.apache.camel.util.SensitiveUtils (maskUserInfoCredentials, maskPemPrivateKeyBlocks, maskSensitiveValueShapes). This is a cosmetic change to masked/logged output only and does not affect endpoint configuration.

If you use DefaultMaskingFormatter with an empty keyword set, format() previously returned the source unchanged; it now still applies URI userinfo and PEM private-key masking on the text.

Push notifications are now delivered with Apache HttpClient 5 instead of java.net.http.HttpClient, so the request can be pinned to the address the webhook URL was validated against.

Previously WebhookUrlValidator resolved the webhook host and applied the SSRF checks, and the HTTP client then resolved the same hostname again when it opened the connection. The two lookups are independent, so the address that was validated and the address actually connected to could differ (DNS rebinding). The connection is now opened to the address that passed validation, while the hostname is still used for the Host header, TLS SNI and certificate hostname verification. Each retry attempt re-validates and re-resolves, so a config that was safe when first dispatched cannot be rebound between retries (which may be up to an hour apart).

camel-a2a therefore has a new dependency on org.apache.httpcomponents.client5:httpclient5.

The PushNotificationDispatcher constructor now takes an org.apache.hc.client5.http.impl.async.CloseableHttpAsyncClient instead of a java.net.http.HttpClient. This only affects code constructing the dispatcher directly; the client must be started before use. Endpoint behaviour is unchanged — redirects were already never followed for push webhooks, and still are not, since a redirect would be resolved by the client and escape the validation applied to the registered URL.

When using the batching consumer (batching=true), the exchange carrying the batch now also has the CamelKafkaTopic and CamelKafkaPartition headers set, so they can be read before the batch is split — for example to store the topic in a variable and reuse it after the split.

A header is only set when every record in the batch has the same value for it; if the batch spans multiple topics or partitions, that header is left unset, because no single value would be correct for the batch. Per-record headers that naturally differ, such as CamelKafkaOffset, are not set on the batch exchange.

This is additive — these headers were previously absent from the batch exchange, so nothing that worked before changes. The headers on the individual record exchanges in the body are unchanged.

The Kafka consumer’s internal reconnection logic has been simplified. Previously, creating a KafkaConsumer (kafka-client) and subscribing to topics were handled by two separate foreground tasks with independent backoff settings. These have been merged into a single background reconnection task that is visible via Camel management, including the TUI, CLI, Hawtio, and other tooling.

As a result, the subscribeConsumerBackoffMaxAttempts and subscribeConsumerBackoffInterval component options are now deprecated and no longer used. The unified reconnection task uses the createConsumerBackoffMaxAttempts and createConsumerBackoffInterval options to control retry behavior for both consumer creation and topic subscription.

If you previously configured subscribeConsumerBackoffMaxAttempts or subscribeConsumerBackoffInterval, migrate those settings to use createConsumerBackoffMaxAttempts and createConsumerBackoffInterval instead.

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.

All camel-aws modules now use software.amazon.awssdk:apache5-client (Apache HttpClient 5) instead of software.amazon.awssdk:apache-client (Apache HttpClient 4), aligning with the new default in AWS SDK for Java v2.46.0.

If your project has <dependencyManagement> entries, exclusions, or explicit dependencies referencing software.amazon.awssdk:apache-client, update them to software.amazon.awssdk:apache5-client.

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.

The onFallbackViaNetwork() DSL method and the fallbackViaNetwork option on onFallback have been deprecated for removal. This was a Hystrix-era concept that has never been supported by any current circuit breaker implementation — both camel-resilience4j and camel-microprofile-fault-tolerance throw UnsupportedOperationException at route initialization when it is enabled. Use onFallback() instead.

The following Resilience4j configuration options now use java.time.Duration type instead of plain integers, and accept Camel duration expressions (e.g. 60s, 1m, PT1M) as well as plain millisecond values:

If you configured waitDurationInOpenState or slowCallDurationThreshold with a plain integer meaning seconds, you must update the value to use a duration suffix (e.g. 60s) or convert to milliseconds (e.g. 60000).

Java DSL:

The int overloads for waitDurationInOpenState(int), slowCallDurationThreshold(int), timeoutDuration(int), and bulkheadMaxWaitDuration(int) have been deprecated. Use the String overloads with Camel duration expressions instead.

Application properties (camel-main, Spring Boot, Quarkus):

If you configure circuit breaker settings via application.properties, the same migration applies:

Programmatic configuration (camel-main):

The same change applies to the Java API in org.apache.camel.main.Resilience4jConfigurationProperties. The getters, setters and fluent builders for waitDurationInOpenState, slowCallDurationThreshold, timeoutDuration and bulkheadMaxWaitDuration now use String instead of Integer, so code that configures the circuit breaker through MainConfigurationProperties must be updated:

timeoutDuration and bulkheadMaxWaitDuration were already expressed in milliseconds, so for those two this is only a type change (quote the value) with no unit conversion; waitDurationInOpenState and slowCallDurationThreshold additionally change from seconds to milliseconds as described above.

The io.vavr:vavr and io.vavr:vavr-match runtime dependencies have been removed from camel-resilience4j. The single internal usage of Vavr’s Try monad has been replaced with a plain try-catch. This eliminates two transitive runtime JARs. No user-facing behavior change.

The JMX managed attribute CircuitBreakerWaitDurationInOpenState previously reported seconds (using Duration.getSeconds()). It now reports milliseconds (using Duration.toMillis()) to be consistent with all other duration attributes (BulkheadMaxWaitDuration, TimeoutDuration) and with the option itself, which was changed from seconds to milliseconds in the same release (see above).

If you have JMX-based monitoring that reads this attribute, update the expected unit from seconds to milliseconds.

The deprecated timeoutPoolSize option has been removed from the Fault Tolerance configuration. This option was never used by SmallRye Fault Tolerance and had no effect. Remove any references to timeoutPoolSize from your configuration.

The JMX attribute FailureRate has been renamed to FailureRatio to match the configuration property name and avoid confusion with live failure rate metrics.

New JMX attributes have been added for live call monitoring:

A new transitionToCloseState JMX operation resets the circuit breaker to CLOSED and clears the call counters.

The IBM MQ client library (com.ibm.mq:com.ibm.mq.jakarta.client) has been upgraded from 9.4.x to 10.0.0.0, and the IBM MQ test container image from 9.4.x to 10.0.0.0.

IBM MQ 10.0 marks the JMS_IBM_MsgToken vendor property as read-only. When Camel copies headers from an incoming JMS message to an outgoing reply or forwarded message, this reserved property previously caused a MessageFormatException that silently prevented the reply from being sent.

When setting JMS properties on an outgoing message, Camel now catches JMSException for JMS vendor-specific properties (those with a JMS_ prefix, per JMS spec section 3.5.1) and logs a WARN instead of propagating the exception. There is no standard JMS API to query which vendor properties are reserved, and the set can change between provider versions. Non-vendor properties still throw on failure as before.

This change is necessary for IBM MQ 10.0 compatibility but applies to all JMS providers. If you relied on exceptions from vendor-specific property failures propagating through JmsBinding.appendJmsProperty(), be aware that they are now caught and logged at WARN level for JMS_-prefixed properties only.

The underlying io.minio:minio library has been upgraded from 8.x to 9.0.3. This release contains several breaking API changes that affect users who pass io.minio objects directly through the Camel Minio component (e.g. via pojoRequest=true or custom MinioClient configuration).

When an AWS2 producer is configured with pojoRequest=true, it expects the Exchange body to be the AWS SDK request object for the selected operation (for example an AssumeRoleRequest for the assumeRole operation of camel-aws2-sts). Previously, if the body was some other type, the operation silently did nothing: no AWS call was made, no response was set, and the original body was returned with no error.

These producers now throw an IllegalArgumentException naming the required request type, consistent with the behaviour already shipped for camel-aws-bedrock in 4.21 (CAMEL-23462). This roll-out across the remaining AWS2 producers is tracked by CAMEL-24261.

If you relied on the previous silent no-op, ensure the body is the correct request type when pojoRequest=true, or drive the operation through headers with pojoRequest=false.

When the consumer is configured with downloadFileName pointing at a directory, the remote object name is appended to that directory to build the local file to write. The resolved path is now verified to stay within the configured directory, and an IllegalArgumentException is thrown if it does not.

Object names are still allowed to contain / and are mapped to sub-directories of the download directory as before, so nested object names keep working unchanged. Only names that resolve outside the configured directory are rejected.

If downloadFileName is configured with an expression (i.e. it contains $), the local path is built by that expression as before and is not subject to this check.

The embedded HTTP server and the management server build their JWT authenticator from the configured keystore. When neither jwtIssuer nor jwtAudience was set, no JWTOptions was applied, so tokens were only checked for signature and expiry and the iss and aud claims were not validated.

The server now fails to start when a JWT keystore is configured but neither camel.server.jwtIssuer nor camel.server.jwtAudience is set (and likewise for camel.management.*). Configure the issuer and/or the audience that tokens are expected to carry.

If a deployment genuinely wants signature and expiry validation only, set camel.server.jwtAllowMissingIssuerAndAudience=true (or camel.management.jwtAllowMissingIssuerAndAudience=true) to keep the previous behaviour.

When unmarshalling a tar or zip archive, the CamelFileName header was previously set to the raw archive entry name, which for a crafted archive can contain path segments (e.g. ../../etc/passwd). If a downstream route wrote the message to disk using that header, the entry name could escape the intended directory (Tar Slip / Zip Slip).

CamelFileName is now set to the entry’s base name only (path segments stripped) for both the data format and the iterator/splitter modes. The full, unmodified entry name remains available so routes that intentionally recreate the archive’s directory structure keep working — read it from CamelTarFileEntryName for tar and from zipFileName for zip instead of CamelFileName.

The ldif producer previously treated a message body that does not start with version: 1 as a URL and dereferenced it (URI.create(body).toURL().openStream()). This content-sniffed URL fetch is now opt-in: a new allowUrlBody option (default false) gates it. With the default, a body that is not LDIF content is rejected with an IllegalArgumentException instead of being fetched, which avoids a content-sniffed URL fetch (SSRF) from untrusted body content. Routes that rely on passing a URL as the body must set allowUrlBody=true on the ldif endpoint.

When typeFilters (or unmarshalType) is configured, the allow-list is now also enforced by the SnakeYAML 2.x TagInspector layer, not only by the getClassForName constructor override. A YAML document that references a disallowed global tag is therefore rejected earlier, during composing, and surfaces as an org.yaml.snakeyaml.composer.ComposerException ("Global tag is not allowed: …​") instead of the previous ConstructorException caused by an IllegalArgumentException. The set of accepted types is unchanged; only the exception raised for a rejected type differs. Routes that do not configure typeFilters are unaffected.

camel-jfr can now also emit JFR events during message routing, in addition to the existing startup instrumentation. This is opt-in and disabled by default, so having camel-jfr on the classpath keeps behaving exactly as it did in 4.21.

Enable it with camel.main.startup-recorder-runtime-enabled=true, or programmatically with setRuntimeEnabled(true) on the FlightRecorderStartupStepRecorder. The option is read once while the CamelContext initializes and cannot be changed afterwards.

org.apache.camel.spi.StartupStepRecorder gained the default methods isRuntimeEnabled() and setRuntimeEnabled(boolean). Both have no-op defaults, so existing implementations continue to compile and behave as before.

The camel-spring-ai-chat, camel-spring-ai-embeddings, camel-spring-ai-image and camel-spring-ai-vector-store components now build on Spring AI 2.0 instead of Spring AI 1.1. Spring AI 1.1 targets Spring Boot 3.5 and Spring Framework 6, while Camel is already on Spring Boot 4.1 and Spring Framework 7, which is the baseline Spring AI 2.0 was designed for. The upgrade also aligns the MCP Java SDK that camel-spring-ai-chat pulls in transitively (previously 0.18.2) with the 2.0.0 version already used by camel-mcp-server and camel-openai.

Applications that configure Spring AI themselves must migrate along with it. The full list of changes is in the Spring AI upgrade notes; the ones most likely to affect a Camel route are:

UndertowEndpoint defaulted its headerFilterStrategy to the base HttpHeaderFilterStrategy, and pushed that strategy into the DefaultUndertowHttpBinding it creates lazily, overwriting the UndertowHeaderFilterStrategy that the binding installs in its own constructor. The undertow-specific filtering was therefore not applied on endpoint-configured routes.

The endpoint now defaults to UndertowHeaderFilterStrategy, which makes two already documented behaviours take effect:

Ordinary application headers are unaffected, and Rest DSL consumers already used an undertow-specific strategy (UndertowRestHeaderFilterStrategy) so their behaviour does not change. Routes that relied on websocket.* headers crossing the undertow boundary in either direction, and routes that relied on undertow-invalid header names being mapped, can restore the previous behaviour by configuring headerFilterStrategy explicitly on the endpoint:

Routes that already supply a custom headerFilterStrategy or a custom undertowHttpBinding are unaffected.

The Exchange header constants in WebsocketConstants 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(WebsocketConstants.CONNECTION_KEY, …​)) continue to work without changes. Routes that set the header by its literal string value must be updated to use the new value:

The sibling websocket components are not affected by this change: camel-undertow keeps the websocket. values in UndertowConstants (as documented in the 4.18 upgrade guide), and camel-vertx-websocket keeps its CamelVertxWebsocket. values.

Note that WebsocketConstants.SEND_TO_ALL is not read by this component. Broadcast is selected through the sendToAll endpoint option, not through the header; the constant is renamed here only to keep the class internally consistent.

The google-mail-stream consumer always asked the Gmail API for the FULL message format, but the raw field is only populated for the RAW format, so raw=true produced a null body. The consumer now requests the format that matches the option.

Because the Gmail API does not return the parsed payload for the RAW format, a route running with raw=true no longer receives the CamelGoogleMailStreamSubject, …​From, …​To, …​Cc, …​Bcc and …​MessageId headers — those values are part of the RFC 2822 content that is now in the body. CamelGoogleMailStreamId, …​ThreadId and …​LabelIds are still set. Routes that need the parsed headers should keep the default raw=false.

Both options were declared and documented but never read, so they had no effect. They now do what they say: