pipelogiqTroubleshoot Java applications
Resolve dependency, configuration, readiness, stage, schedule and agent issues using the typed SDK.
Start with the first failing boundary: package resolution, configuration, worker connection, dispatch or business execution. Keep the pipeline ID and stage status when investigating a workflow.
Dependencies and startup
| Symptom | What to check |
|---|---|
com.pipelogiq dependency cannot be resolved | Install matching source modules into the same local Maven repository. These guides do not assume Central publication. |
Old io.pipelogiq Maven coordinate | Use group com.pipelogiq; Java imports still start with io.pipelogiq.sdk. |
| Unsupported class-file version | Use JDK 17 or 21; check both java -version and Maven's Java version. |
| Configuration file not found | Paths are relative to the working directory. Use an absolute path or classpath:pipelogiq.yml. |
| Missing API key / unresolved placeholder | Export the variable in the terminal or service environment starting this process. |
| Unknown YAML property | Use the exact supported settings. Spring's auto-startup is not a standalone YAML property. |
| Duplicate handler name | Check annotations and repeated registrations. Registration fails instead of choosing silently. |
| Cannot instantiate a stage | .stages(...) needs an accessible no-argument constructor. Use a factory or Spring for constructor injection. |
| Unresolved input type | Use a concrete StageHandler<Order>; raw or unresolved generic handlers cannot supply an input contract. |
Worker cannot become ready
Verify the API URL and application API key first. An authentication failure cannot be repaired by increasing startup timeout. For AMQP, check the broker address returned by bootstrap and reachability from the worker; use PIPELOGIQ_RABBITMQ_URL only when an override is necessary.
run() and start() check readiness. A built handle has not started until you call start(). Selecting AMQP does not fall back to HTTP. Logs and the startup exception identify the failing boundary.
Pipeline stays pending or fails
Use the basic demo's typed commands, replacing 123 with your pipeline ID:
java -cp 'target/classes:target/dependency/*' example.CreatePipelineExample get 123
java -cp 'target/classes:target/dependency/*' example.CreatePipelineExample wait 123 60| Observation | Next check |
|---|---|
| Pending work and no attempts | Keep a ready worker online in the same application. Compare handler names with registrations. |
VALIDATION_ERROR | Check the input contract; context.require also uses this code for incompatible present data. |
MISSING_REQUIRED_DATA | Check the preceding stage's context output and dependency order. |
| Repeated submission returns an old ID | The idempotency key reuses the original request. Use a new key for a new run. |
| Completion wait times out | The local observation deadline expired; it did not cancel the pipeline. |
| Future cancellation did not stop business work | Future cancellation is local. Use client.pipelines().cancel(id) for server cancellation; business code must cooperate. |
| Side effect happened twice | Delivery is at least once. Deduplicate the action where it takes place. |
| Parallel stages overwrite data | Write distinct context keys or join branches before modifying shared values. |
An execution ID belongs to an attempt, so it is unsuitable as the only retry-stable key for an external action.
Schedule does not fire as expected
Use ScheduleExample get <name> and history <name>. Check status, next run time, IANA zone, five-field cron expression and server health/history. Intervals must be whole seconds and at least 10 seconds. A one-time schedule is archived after firing.
Manual triggering does not advance the schedule cursor. An unchanged upsert does not restart its timing. A scheduled pipeline can exist while waiting for an online worker. See schedule operations.
Agent and Spring checks
Run the deterministic agent example before adding provider credentials. A successful fixture proves your tool/approval scenario, not provider authentication. Use a model available to your account and keep credentials in worker configuration.
Approve the actual waiting stage through an authorized approval surface. A delivered notification is not approval. Workers registering built-in agent handler names need compatible configuration or separate Pipelogiq applications.
For Spring, stages must be beans. An application with no stage beans intentionally creates only a producer client. Check pipelogiq.auto-startup, profiles and configuration sources. Singleton stages can execute concurrently; use the SDK invocation scope for a per-attempt dependency graph.
Collect a diagnostic report
Include SDK and Java versions, transport, pipeline/stage IDs, status/error code and relevant configuration keys with secret values removed. Preserve the exception and whether failure occurred before or after submission. Do not paste application keys, broker passwords, provider keys or sensitive context into reports.