Breadcrumbs

Troubleshooting

Summary: Common IM runtime errors — symptoms, root causes, and solutions.

Connection Errors

ConnectException: Connection refused

Symptom: Route fails immediately on startup or first API call.

Root cause: IM cannot reach the Pricefx server or a 3rd-party system.

Solutions:

  • Verify the URL in integration.pfx.url or connection JSON file

  • Check network/firewall rules — provisioned instances need outbound access to *.pricefx.eu

  • If using SFTP/REST: verify host and port in the connection configuration

  • Check if the target system is up and accessible from the IM instance

ConnectTimeoutException / SocketTimeoutException

Symptom: Route hangs for a while, then fails with timeout.

Root cause: Network latency or the target system is overloaded.

Solutions:

  • IM retries these automatically (default: 10 retries with exponential backoff)

  • If persistent: check if the Pricefx partition is under heavy load

  • For SFTP: increase timeout with connectTimeout and soTimeout parameters

  • For REST: set httpClient.socketTimeout and httpClient.connectionTimeout

SSLHandshakeException / Certificate errors

Symptom: Connection fails with SSL/TLS errors.

Solutions:

  • For self-signed certs: upload the certificate via PlatformManager and reference it in the connection

  • Verify the certificate chain is complete

  • Check if the certificate has expired

Data Loading Errors

NonRecoverableException / PfxApiException

Symptom: pfx-api call fails immediately without retry.

Root cause: A permanent error — the request is invalid and retrying won't help.

Common messages:

  • "Parameter 'objectType' must be present" — missing objectType in URI

  • "Mapper definition wasn't found" — mapper bean ID doesn't match any mapper file

  • "Body must be defined when using 'pfx-api:import'" — exchange body is null

  • "Unknown object type: [type]" — typo in objectType value

  • "Pricing parameter id or name not specified" — LTV/MLTV2 missing pricingParameterName

  • "ConditionRecordSetId or ConditionRecordSetName must be defined in the mapper" — condition record mapper incomplete

Solution: Read the error message carefully — it tells you exactly what's missing. These are configuration errors, not data issues.

IllegalStateException: Mapper attribute 'name' is required for extension types

Symptom: PX or CX import fails immediately.

Root cause: The mapper is missing <constant expression="TableName" out="name"/>.

Solution: Add the table name as a constant to the mapper:

XML
<loadMapper id="my-mapper">
    <constant expression="Cars" out="name"/>  <!-- required for PX/CX -->
    <body in="sku" out="sku"/>
    ...
</loadMapper>

HTTP 409 Conflict on loaddata

Symptom: Load fails with 409 status, often during concurrent imports.

Root cause: Another load or flush is already in progress for the same target.

Solutions:

  • Ensure only one route loads into the same target simultaneously

  • Wait for previous load/flush to complete before starting a new one

  • IM retries 409 automatically — if transient, it resolves itself

HTTP 413 Payload Too Large

Symptom: Load fails when sending large batches.

Root cause: Batch size too large for the server.

Solution: Reduce batchSize in the route URI:

  • < 10 fields per row: batchSize=500000

  • 10–20 fields: batchSize=100000–200000

  • 20+ fields: batchSize=50000 or less

Data loaded but not visible in Pricefx

Symptom: loaddata succeeds, but data is not in Pricefx.

Root causes:

  1. Missing flush (DMDS) — Data Source imports require pfx-api:flush after loading. Without it, data remains in staging.

  2. Wrong dsUniqueName — Check that dsUniqueName, dataFeedName (DMF.X), and dataSourceName (DMDS.X) all use the same name.

  3. onCompletion inside split — The flush runs after every batch, not once at the end. Move onCompletion outside the <split> block.

Solution for DMDS:

XML
<route id="import-ds">
    <from uri="file:..."/>
    <split ...>
        <to uri="pfx-api:loaddata?objectType=DM&amp;dsUniqueName=Product&amp;mapper=myMapper"/>
    </split>
    <onCompletion onCompleteOnly="true">
        <to uri="pfx-api:flush?dataFeedName=DMF.Product&amp;dataSourceName=DMDS.Product"/>
    </onCompletion>
</route>

FormatException: Value doesn't have the required format

Symptom: Records fail during mapper processing.

Root cause: A field value doesn't match the expected converter format (e.g., stringToDecimal on a non-numeric string).

Solutions:

  • Fix source data to match expected format

  • Use convertEmptyStringToNull="true" on the mapper to handle empty strings

  • Use skipInvalidRecords="true" to log and skip bad records

  • Add a default value to the converter: converterExpression="stringToInteger('0')"

Records rejected / partial failures

Symptom: Some records load, others are silently dropped.

Root causes:

  • Business key mismatch — businessKeys value doesn't match the mapper output field

  • Required fields missing (e.g., sku for Products, customerId for Customers)

  • Data type mismatch — string value where a number is expected

Solution: Enable skipInvalidRecords="true" on the mapper to log rejected records, then fix the source data or mapper.

Fetch / Export Errors

HTTP 400 Bad Request on fetch

Symptom: Fetch fails with 400 status.

Root causes:

  • Invalid filter syntax — check fieldName, operator, value

  • Non-existent field name in filter criterion

  • Invalid objectType value

  • Missing required parameter (e.g., pricingParameterName for LTV/MLTV2)

Solution: Verify the filter XML. Common mistakes:

  • Using equal instead of equals as operator

  • Missing simple: prefix for dynamic values: value="simple:${header.myHeader}"

  • Referencing a non-existent filter bean ID

OutOfMemoryError on large exports

Symptom: IM runs out of memory when exporting large datasets.

Root cause: Fetching all records into memory at once.

Solution: Use batched mode:

XML
<to uri="pfx-api:fetch?objectType=PX&amp;filter=myFilter&amp;batchedMode=true&amp;batchSize=5000"/>
<split>
    <simple>${body}</simple>
    <to uri="pfx-api:fetchIterator"/>
    <to uri="pfx-csv:marshal"/>
    <to uri="file:export?fileName=data.csv&amp;fileExist=Append"/>
</split>

Empty result set (no data returned)

Symptom: Fetch returns 0 records when you expect data.

Root causes:

  • Filter criteria too restrictive

  • For PX/CX: missing name criterion — PX/CX fetch requires a filter with fieldName="name" to identify the extension table

  • Wrong objectType — e.g., using PX when the data is in a Data Source (DM)

  • Case-sensitive field values — Pricefx field values may be case-sensitive

Route Startup Errors

Failed to start route: Route ID mismatch

Symptom: IM fails to start, route not found or not loaded.

Root cause: The route ID doesn't match the file name.

Rule: File import-products.xml → route ID must be import-products. See Routes.

Mapper/filter bean not found

Symptom: Route fails with "No bean could be found" error.

Root cause: The mapper or filter referenced in the route URI doesn't exist or has a mismatched ID.

Check:

  • Mapper file mappers/my-mapper.mapper.xml → mapper ID must be my-mapper.mapper

  • Filter file filters/my-filter.filter.xml → filter ID must be my-filter.filter

  • File name and ID must match exactly (case-sensitive)

XML parsing error on route file

Symptom: IM fails to parse route XML.

Common causes:

  • Using & instead of &amp; in URI attributes

  • Missing xmlns="http://camel.apache.org/schema/spring" on <routes> element

  • Invalid XML characters in expressions

  • Unclosed XML elements

File Processing Errors

File not picked up

Symptom: File is in the directory but the route doesn't process it.

Root causes:

  • File still being written — if using {{read.lock}} (readLock=changed), IM waits for the file to stabilize

  • Missing .done marker — if using {{done.file}}, IM waits for filename.done

  • File already processed — check .archive/ directory

  • include pattern doesn't match the file name

  • Wrong directory path in application.properties

CSV parsing errors

Symptom: pfx-csv:unmarshal fails with parse error.

Common messages:

  • "Header parameter must be defined because headerPolicy is strict" — CSV has no header row but skipHeaderRecord=true is set

  • "Required header is different from header in data" — header parameter doesn't match actual CSV columns

  • "Streaming unmarshal can't be used inside of a route split" — streamingUnmarshal must be used before the <split>, not inside it

Solutions:

  • Verify the CSV has a header row if skipHeaderRecord=true

  • If no header row, specify columns explicitly: header=sku,name,price

  • Move streamingUnmarshal before the split element

File processed but no data loaded

Symptom: File is moved to archive, but no data in Pricefx.

Root causes:

  • CSV header mismatch — column names don't match mapper in fields

  • Empty file (only header row)

  • Wrong delimiter — default is , but file may use ; or \t

  • Encoding mismatch — file uses a different encoding than expected

Solution: Check CSV parsing with pfx-filepreview:preview to see what IM reads from the file.

Event Handling Errors

Events not being processed

Symptom: Pricefx events fire but IM doesn't react.

Root causes:

  • integration.events.enabled=false (default) — must be set to true

  • Wrong event type in mapping — e.g., PADATALOAD_COMPLETED vs PA_DATALOAD_COMPLETED

  • Route URI mismatch — the direct: URI in the mapping must match the route's <from> URI

Stuck events

Symptom: Events accumulate and are never processed.

Root cause: A previous event handler route failed or is still running.

Solutions:

  • Check stuck event monitoring: integration.events.check-stuck-processing.enabled=true (default)

  • Manually clear stuck events via the Pricefx API

  • Check IM logs for the failed route and fix the root cause

Groovy Errors

SecurityException: Groovy sandbox violation

Symptom: Groovy expression fails with security exception.

Root cause: The expression uses a class or method not allowed by the Groovy sandbox.

Solutions:

  • Check the whitelist in the Groovy Sandbox documentation

  • Use only whitelisted Java classes (String, Math, BigDecimal, etc.)

  • No anonymous inner classes

  • No reflective access

TimeoutException: Groovy execution timeout

Symptom: Groovy expression is killed after timeout.

Root cause: Script takes too long (default limit configured by integration.groovy-sandbox.timeout).

Solutions:

  • Optimize the Groovy logic — avoid loops over large collections

  • If legitimate: increase integration.groovy-sandbox.timeout value (in seconds)

  • Consider moving complex logic to a Groovy processor class instead of inline expression

See Also

Import Errors

OutOfMemoryError during CSV import

Cause: File too large, missing streaming, or batch size too high.

Fix:

  1. Enable streaming: streaming="true" on <split>

  2. Reduce batch size: <tokenize group="10000">

  3. Add <setBody><constant/></setBody> after loaddata (releases memory per batch)

MalformedInputException / Encoding error

Cause: File encoding doesn't match configured charset.

Fix:

  1. Check actual file encoding: file -I filename.csv

  2. Set charset in route: <toD uri="pfx-io:setupCharset?specifiedCharset=ISO-8859-1"/>

  3. Add doCatch to fail cleanly (see Error Handling Pattern)

Records loaded but not visible in Pricefx

Cause (DMDS): Missing flush after load.

Fix: Add flush after split completes:

XML
<toD uri="pfx-api:flush?dataFeedName=DMF.${headers.dsUniqueName}&amp;dataSourceName=DMDS.${headers.dsUniqueName}"/>

Cause (PPV): Wrong pricingParameterName or missing name constant in mapper.

Data loaded with wrong values / all nulls

Cause: Mapper field names don't match CSV headers (case-sensitive).

Fix: Check CSV headers match in= attribute in mapper. Enable skipInvalidRecords="true" temporarily to identify which records fail.

Export Errors

Export runs but produces empty file

Cause: Timestamp tracking returns future date, or WHERE clause filters out all records.

Fix:

  1. Check pfx-config value: pfx-config:get?name=...

  2. Reset timestamp: pfx-config:set?name=...&value=2020-01-01T00:00:00

  3. Test query manually in Pricefx admin

Quartz schedule doesn't fire

Cause: Wrong cron syntax (spaces instead of + in URI) or missing timezone.

Fix: In URI, use + as separator: cron=0+0+2+?+*+* and always set trigger.timeZone.

Connection Errors (Additional)

Trust store password error

Cause: Wrong default.truststore.password or read-only cacerts in container.

Fix: Copy the trust store to a writable location and set the javax.net.ssl.trustStore system property.

SFTP connection refused / timeout

Cause: Firewall, wrong port, or SSH key mismatch.

Fix:

  1. Test connectivity: sftp user@host from the IM container

  2. Check connection JSON for correct host/port/credentials

  3. Verify SSH key type is supported (RSA, ECDSA)

Certificate deployment fails (Permission denied)

Cause: Container runs as non-root, can't write to $JAVA_HOME/lib/security/cacerts.

Fix: Copy cacerts to writable location in Dockerfile, set -Djavax.net.ssl.trustStore.

Event Route Errors

Event route never triggers

Cause: Event type not mapped in properties.

Fix: Add mapping:

integration.events.event-to-route-mapping.MY_EVENT=direct:eventMY_EVENT

Event processed multiple times

Cause: Missing idempotency check or route restarted during processing.

Fix: Use event ID as idempotent key, or check for duplicate processing in handler.

Performance Issues

Import taking too long

  1. Increase batch size (if memory allows)

  2. Enable streaming if not already

  3. Check if unnecessary CFS calculations triggered per-batch (should be onCompletion only)

  4. Use start/stop scheduling for large overnight loads (see Scheduling Pattern)

API rate limiting / 429 errors

  1. Reduce batch concurrency (don't use parallelProcessing on split)

  2. Add redelivery with exponential backoff

  3. Reduce batch size to decrease per-call payload