Skip to content

Troubleshooting

A short checklist of common issues and how to fix them when building and running Fluxtion DataFlows.

Nothing happens when I send events

  • Verify you actually subscribed to the right type or key:
  • subscribe(String.class) for raw String events
  • subscribe(MyEvent::field) if you want to project a field from a POJO
  • Ensure you call build() (functional DSL) or finish constructing the SEP before invoking onEvent.
  • If using sinks, confirm you added a sink or a console call at the end of the chain: .console("msg:{}") or .sink("id").

Time windows not updating

  • Windowing operators depend on time; register a clock source. At startup publish a clock event using ClockStrategy: 
    import static com.telamin.fluxtion.runtime.time.ClockStrategy.registerClockEvent;

dataFlow.onEvent(registerClockEvent(() -> System.currentTimeMillis()));
  • In tests, use a controllable clock. If you extend the provided test utilities, call setTime(...), advanceTime(...), or tick() to drive time.

Determinism and order look wrong

  • Fluxtion executes nodes in topological order with at‑most‑once invocation per node per event. If results seem stale:
  • Check each node declares its dependency via the builder chain (e.g., ensure the node that should trigger another is actually upstream).
  • Avoid side effects that bypass the graph; instead pass values through the DataFlow so dependencies are tracked.

Logging and debugging

  • Quick visibility: add .console("msg:{}") at the end of a chain to print values.
  • For structured auditing, enable the event log auditor (see reference) and inspect the last audit record via dataFlow.getLastAuditLogRecord().
  • Tests include logcaptor and system-rules to capture output if you need assertions on logs.

IDE or tests fail with IllegalAccessError

  • The build config opens jdk.internal.misc for some dependencies via Surefire:
  • Maven Surefire already includes: --add-opens java.base/jdk.internal.misc=ALL-UNNAMED.
  • If running in your IDE, mirror this JVM option in your run configuration if you encounter IllegalAccess problems.

Java version

  • Fluxtion targets Java 21. Ensure your project uses a Java 21 toolchain and your IDE is set to 21 for compiling and running examples.

Kafka or external I/O integration

  • Fluxtion is infrastructure‑agnostic. For Kafka, consume records, publish to the DataFlow via onEvent, then produce results. Start with at‑least‑once: commit offsets after successful processing. See the Integrations guide.

High Tail Latency (p99/p99.9 spikes)

  • Identify the Bottleneck: Use the Monitoring Guide to measure node-level execution time.
  • Blocking Sinks: Fluxtion is single-threaded by design. If a Sink performs a blocking I/O call (e.g., a slow database write), it will stall the entire event processor.
    • Fix: Use asynchronous sinks or internal buffering if the destination system is slow.
  • GC Interference: While Fluxtion is zero-GC on the hot path, your own node logic or external libraries might be allocating.
    • Fix: Profile with JFR (Java Flight Recorder) to identify allocation hot spots.

Memory Leaks or OutOfMemoryError

  • Large Time Windows: Sliding windows with many buckets or long durations can consume significant memory.
    • Fix: Reduce bucket count or window duration if memory is tight.
  • Unbounded Collections: Avoid growing collections (Lists/Maps) inside nodes without a cleanup strategy.
    • Fix: Use bounded buffers or Fluxtion's built-in windowing/aggregation functions.

Threading Issues and Race Conditions

  • Thread Safety: The DataFlow instance is NOT thread-safe for concurrent onEvent calls.
    • Fix: Use DataFlowConnector to manage single-threaded delivery, or synchronize your own calls to onEvent.
  • External State Access: If your nodes access shared external state, ensure that access is thread-safe or (preferably) move the state into the DataFlow graph itself.

Mongoose Integration Issues

  • Feed Mismatch: If events are not reaching your processor in Mongoose, verify the feed name in subscribeToFeed("name", ...) matches the name in your Mongoose YAML configuration.
  • Plugin Loading: Ensure your DataFlow JAR is correctly placed in the Mongoose plugins/ directory and that its package is scanned for discovery.

AOT Compilation Errors

  • Missing Compiler: If you expect an AOT-optimized dispatcher but see interpreted behavior, ensure the fluxtion-compiler is in your build classpath (provided scope).
  • Annotation Processing: If using the Imperative model, ensure your IDE or build tool has annotation processing enabled to detect @OnEventHandler and @Start/@Stop annotations.

Still stuck?

  • Check the Examples page and Reference guide for a code snippet matching your use case.
  • Open an issue with a minimal reproducer on GitHub if the behavior still surprises you.