Troubleshooting: start-up errors, TLS failures and exception kinds

What Cameleer's error messages mean and how to fix them: routes that fail to load or start (an unknown step, component or option, a missing property or bean, a port in use), errors while messages flow (no consumer, connection refused, HTTP status codes), TLS handshake failures, and the exception kinds that onException and doCatch match, with their hierarchy.

Applies to: cameleer run, cameleer validate and programs that embed Cameleer · Apache Camel: the messages and exception names follow Camel's, so most Camel answers apply

Where to start

1. Run cameleer validate on the route files. It finds most start-up errors without starting anything, with the file, line and column, and often suggests the name you meant (Validate route files).
2. Read the first line of the error, then the last caused by. A start-up error prints one line, Error: <kind>: <message> (caused by <kind>: <message>), and cameleer run exits with
   1. The innermost cause names what is actually wrong.
3. Turn up the logging with --log-level DEBUG (or camel.main.log-level=DEBUG), and use --trace to print every message as it moves through the routes.
4. Ask the running integration: cameleer get routes shows each route's state and failure count, cameleer get health the health checks, and cameleer log --follow its log (the cameleer command line).

The same commands with the container image, from the folder that holds the route files:

cameleer validate routes/
cameleer run routes/orders.camel.yaml --log-level DEBUG --trace

docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer validate /routes/routes
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/routes/orders.camel.yaml --log-level DEBUG --trace

A program that embeds Cameleer gets the same errors as Err(CamelError) from start() or add_routes, with the same kind and message; the Rust developer guide shows the API.

Routes that fail to load or start

Unknown step

Error: YamlDeserializationException: Error loading routes from orders.camel.yaml: Unknown step 'sett' at [0].route.from.steps[0].sett (line 5, column 11). Supported steps: agent, aggregate, bean, choice, ...

A step name is misspelled or is not a YAML DSL step. The message lists every step; cameleer validate reports error[dsl-structure]: unknown step 'sett' with a "did you mean" hint. Step names are case-sensitive and follow Camel's (setBody, toD, doTry); the YAML DSL reference lists their keys.

Invalid YAML

Error: ParseException: Error loading routes from orders.camel.yaml: Invalid YAML: bad indentation of a mapping entry at line 4, column 6

The file is not valid YAML: usually indentation, a tab character, or an unquoted value that contains : or starts with {, * or &. Quote values with special characters, in particular Simple expressions (simple: "${body} contains 'x'").

No component found with scheme

Error: FailedToCreateRouteException: Failed to create route route1 at: >>> to[kafak:orders] <<< because of Failed to resolve endpoint: kafak://orders due to: No component found with scheme: kafak

Either the scheme is misspelled (cameleer validate suggests kafka), or the binary was built without that component family. In a smaller build the message ends with the fix, for example (this cameleer binary was built without the kafka-mqttfeature; rebuild cameleer-main with--features kafka-mqtt). The Docker image and cargo install cameleer-main have every component; Build features lists the families. cameleer catalog components lists the schemes of the binary you have.

Unknown parameters

Error: FailedToCreateRouteException: Failed to create route route1: Failed to resolve endpoint: timer://t?perod=1000 due to: There are 1 parameters that couldn't be set on the endpoint. Check the uri if the parameters are spelt correctly and that they are properties of the endpoint. Unknown parameters=[perod]

An endpoint option is misspelled or is not an option of that component, decided the same way as in Apache Camel. The component's page lists every option; option names are case-sensitive (repeatCount, not repeatcount).

Property with key not found

Error: FailedToCreateRouteException: Failed to create route route1 at: >>> to[{{orders.target}}] <<< because of Property with key [orders.target] not found in properties from text: {{orders.target}}

A {{placeholder}} has no value. Set it in application.properties, with --prop orders.target=..., or with the environment variable CAMEL_PROPERTY_ORDERS_TARGET, or give it a default in the route: {{orders.target:log:orders}}. cameleer validate reports it as a warning, unresolved-placeholder, because the value often comes from where the route runs. Configuration lists every source and the order in which they apply.

No bean could be found in the registry

Error: FailedToCreateRouteException: Failed to create route route1 at: >>> process[ref:enrichOrder] <<< because of No bean could be found in the registry for: enrichOrder

The route refers to a processor, strategy, data source or other bean by name, and nothing is bound under that name. Beans come from Rust code (ctx.registry().bind_processor(...), see the Rust developer guide), from camel.beans.* with a registered bean factory, or, for data sources, from camel.datasource.*. A route file run by the plain cameleer binary cannot use Java classes or beans; use a script step (js, groovy, python) or a built-in EIP instead. cameleer validate does not report a missing processor or endpoint bean, since those can come from code; it does report an aggregationStrategy name that is neither built in nor bound.

Invalid expression

Error: FailedToCreateRouteException: Failed to create route route1 at: >>> setBody[simple{${body}] <<< because of expected symbol functionEnd but was eol at location 0

The expression does not compile: here a Simple expression is missing its closing }. The cause is an ExpressionIllegalSyntaxException; cameleer validate reports it as error[expression] with the position.

Port already in use

Error: FailedToStartRouteException: Failed to start route route1 because of Failed to bind HTTP server on 0.0.0.0:8080: ...

Another process, often an earlier run of the same integration, listens on the port. The text after the colon comes from the operating system ("Address already in use" on Linux, "Only one usage of each socket address" on Windows). cameleer ps lists running integrations and cameleer stop --all stops them; or choose another port with --port or camel.server.port. The management port (camel.management.port, 9876 by default) can clash the same way.

Global SSL context parameters are not configured

useGlobalSslContextParameters=true on https but no global SSL context parameters are configured (camel.ssl.enabled=true / CamelGlobalSSLContextParameters)

An endpoint or component asks for the global TLS settings, and there are none. Set camel.ssl.enabled=true with the camel.ssl.* keys, or bind them from Rust; see TLS and security.

Needs the ai feature

camel.server.mcp-enabled=true needs the ai feature: rebuild with --features ai

The MCP server, ai-tool and the agent step are in the ai feature, which the default build, the Docker image and cargo install cameleer-main have. A binary built with --no-default-features needs --features ai.

Errors while messages flow

These do not stop the integration. The exchange fails, the error handler retries it if redelivery is configured, and the failure is logged:

ERROR [Camel timer://t] DefaultErrorHandler : Failed delivery for (MessageId: ...). Exhausted after delivery attempt: 1 caught: DirectConsumerNotAvailableException: No consumers available on endpoint: direct://nowhere.

TLS handshake failures

TLS failures are SSLPeerUnverifiedException (the certificate) or SSLHandshakeException (the handshake), both kinds of SSLException and IOException, so an onException for IOException catches them too.

Cameleer verifies every certificate chain and host name by default. trustAllCertificates exists for tests; never use it in production. TLS and security has every TLS setting.

Exception kinds

An error in Cameleer has a kind, named like the Java exception class Camel would throw. Kinds have parents, so onException and doCatch for a kind also catch its subkinds, as Java subclasses would be caught. A kind that is not in the table, such as a component's own (YamlDeserializationException), is a RuntimeException. Java class names with a package (java.io.IOException) match by their simple name.

CallNotPermittedException comes from an open circuit breaker, ThrottlerRejectedExecutionException from a throttler with rejectExecution, and PredicateValidationException from the validate EIP. A processor written in Rust picks any kind (CamelError::new("OrderRejected", "...")) and can give a new kind a parent with register_kind_parent("OrderRejected", "IllegalArgumentException") (Rust developer guide). This table is checked against the code by troubleshooting_kinds_match_the_code in crates/cameleer-main/tests/docs_reference.rs, and the messages on this page by troubleshooting_messages_match_the_binary.

Common questions

cameleer validate says the routes are valid, but cameleer run fails. Why?

Validate starts nothing, so it cannot see what only exists at run time: processors bound from Rust, ports already in use, a broker that is down, certificates. Missing placeholders are warnings there; pass the same properties with --properties and use --strict to fail on them.

How do I see the message that failed?

The error handler logs the exchange id. --trace (or cameleer trace on a running integration) prints each message with its body and headers at every step; a dead letter channel keeps failed messages (Error handling).

Where are the logs?

On standard output, in Camel's format (time LEVEL [thread] logger : message). cameleer log --follow shows them for an integration started in the background; in a container, docker logs.

Why does an error mention a Java class?

Kinds are named after the exceptions Apache Camel throws, so Camel's documentation, Stack Overflow answers and existing onException clauses still apply. No JVM is involved.

Related

• Validate route files, the cameleer command line
• Error handling, Observability
• TLS and security, Configuration
• What Cameleer does not do

Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building with it, please help fix it, whether you are a person or a coding agent: open an issue that describes what you saw, then fork the repository, fix it, add or update a test, run cargo test --workspace, and open a pull request. CONTRIBUTING.md explains the ground rules.