Troubleshooting Guide - Development

Common build and development issues when creating Quarkus Flow workflow applications that integrate with Data Index.

This guide is for developers building and testing Quarkus Flow applications locally. For deployment and runtime issues, see Operations Troubleshooting.

Build Issues

Build fails: "At least one enabled entry must be active"

Symptom:

[ERROR] At least one enabled entry must be active, but none were (quarkus-kubernetes)

Cause: Maven profile for KIND deployment not activated.

Solution:

Activate the profile in your workflow application:

mvn clean package -Pkind

Build fails: "Cannot find quarkus-kind"

Symptom:

[ERROR] Unknown deployment target: kind

Cause: Missing quarkus-kind extension.

Solution:

Add to your workflow application’s Maven profile:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-kind</artifactId>
</dependency>

Logging Configuration

No JSON events in logs

Symptom:

$ kubectl logs -n workflows my-workflow-app-xxx | grep eventType
# (no output)

Cause: Structured logging not configured correctly.

Solution:

Verify your workflow application’s application.properties has:

quarkus.flow.structured-logging.enabled=true
quarkus.flow.structured-logging.events=workflow.*
quarkus.flow.structured-logging.timestamp-format=epoch-seconds

quarkus.log.handler.console."FLOW_EVENTS_CONSOLE".enabled=true
quarkus.log.handler.console."FLOW_EVENTS_CONSOLE".format=%s%n

quarkus.log.category."io.quarkiverse.flow.structuredlogging".handlers=FLOW_EVENTS_CONSOLE
quarkus.log.category."io.quarkiverse.flow.structuredlogging".use-parent-handlers=false
quarkus.log.category."io.quarkiverse.flow.structuredlogging".level=INFO

Common mistake: Using io.quarkiverse.flow instead of io.quarkiverse.flow.structuredlogging.

See: Quarkus Flow Integration Guide

File handler errors

Symptom:

LogManager error of type OPEN_FAILURE: Failed to set log file
java.io.FileNotFoundException: /var/log/quarkus-flow/events.log (No such file or directory)

Cause: Quarkus Flow auto-creates a file handler, but pods don’t have write access to /var/log/quarkus-flow/.

Solution:

Disable the file handler in your workflow application’s application.properties:

quarkus.log.handler.file."FLOW_EVENTS".enabled=false

Or use a profile-specific setting:

%prod.quarkus.log.handler.file."FLOW_EVENTS".enabled=false

This is a warning - the app may still start, but disabling the handler prevents the error.

Local Development

Dev Services not starting

Symptom:

PostgreSQL container not starting with mvn quarkus:dev.

Cause: Docker not running.

Solution:

docker info
# If error, start Docker Desktop

Port conflicts

Symptom:

Port 8080 already in use

Cause: Another application using the default Quarkus port.

Solution:

Override the port:

mvn quarkus:dev -Dquarkus.http.port=8081

Or add to application.properties:

%dev.quarkus.http.port=8081

Getting Help

For deployment and runtime issues: - See: Operations Troubleshooting

For configuration: - See: Quarkus Flow Integration - See: Configuration Reference

For Data Index issues: - Check: Local Development Guide