Troubleshooting

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"/>
    <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:

Missing flush (DMDS) -- Data Source imports require pfx-api:flush after loading. Without it, data remains in staging.
Wrong dsUniqueName -- Check that dsUniqueName, dataFeedName (DMF.X), and dataSourceName (DMDS.X) all use the same name.
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 & 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