Troubleshooting #

Common issues and diagnostic steps for XPro.

Database Connection Failures #

Symptom: xpro dbcheck fails or processor cannot connect to the database.

Steps:

1. Verify credentials in /etc/xpro/xpro.env
2. Test connectivity manually:

   # PostgreSQL
   psql -h $XPRO_DB_HOST -U $XPRO_DB_USER -d $XPRO_DB_NAME
   
   # Oracle — ensure Instant Client is installed
   sqlplus $XPRO_DB_USER/$XPRO_DB_PASS@$XPRO_DB_HOST:$XPRO_DB_PORT/$XPRO_DB_NAME
   

3. Check that the database user has CREATE TABLE and INSERT privileges
4. For Oracle, confirm Oracle Instant Client is installed and LD_LIBRARY_PATH is set

NATS Connection Issues #

Symptom: File watcher or processor cannot connect to NATS.

Steps:

1. Verify NATS is running:

   nats server check connection --server $XPRO_NATS_URL
   

2. Check the NATS URL and credentials path in config
3. If using TLS, ensure the credentials file at XPRO_NATS_CREDS is readable by the xpro user
4. Check firewall rules for port 4222

XML Parse Errors #

Symptom: Processor reports XML parsing failures for specific files.

Common causes:

• Invalid characters: XML files containing control characters (e.g., U+000C form feed) that are not valid in XML 1.0
• Encoding mismatch: File declares UTF-8 but contains non-UTF-8 bytes
• Malformed XML: Missing closing tags, unescaped special characters

Steps:

1. Validate the XML file:

   xmllint --noout problem-file.xml
   

2. Check for control characters:

   grep -P '[\x00-\x08\x0B\x0C\x0E-\x1F]' problem-file.xml
   

3. Review processor logs for the specific error and file name:

   journalctl -u xpro-processor | grep "parse error"
   

ORA-01461: LONG Data Binding Error #

Symptom: Oracle database inserts fail with ORA-01461 when using XMLTYPE columns.

Cause: The XML content exceeds the bind size limit for LONG data types.

Fix: Ensure the database schema uses CLOB or XMLTYPE storage, not VARCHAR2. Check your table definition:

SELECT column_name, data_type FROM user_tab_columns
WHERE table_name = 'BILL_DATA' AND column_name = 'XML_CONTENT';

File Watcher Not Detecting Files #

Symptom: Files arrive in sourceDir but the watcher does not pick them up.

Steps:

1. Check that the xpro user has read access to sourceDir:

   sudo -u xpro ls /data/xpro/incoming/
   

2. On Linux, check inotify limits:

   cat /proc/sys/fs/inotify/max_user_watches
   

   If too low, increase it:

   echo 65536 | sudo tee /proc/sys/fs/inotify/max_user_watches
   # Make permanent
   echo 'fs.inotify.max_user_watches=65536' | sudo tee -a /etc/sysctl.conf
   sudo sysctl -p
   

3. Verify the watcher config sourceDir path matches where files are being placed
4. Check watcher logs:

   journalctl -u xpro-file-watcher -f
   

Service Won’t Start #

Symptom: systemctl start xpro-processor fails.

Steps:

1. Check the service status for error details:

   sudo systemctl status xpro-processor
   journalctl -u xpro-processor --no-pager -n 50
   

2. Verify the config file exists and is valid YAML:

   cat /etc/xpro/config.yml
   

3. Check file permissions — config files should be owned by root:xpro with 0640:

   ls -la /opt/xpro/etc/
   

4. Ensure the xpro system user exists:

   id xpro
   

Trial Expired #

Symptom: XPro exits immediately with a trial expiration message.

Options:

1. Install a license file at /opt/xpro/etc/license.key
2. Contact info@bluefunda.com for Enterprise licensing
3. Check trial status:

   xpro version
   

The trial state is stored at /opt/xpro/data/.xpro.state and is bound to the machine ID. It cannot be reset or transferred.

libxml2 Missing or Incompatible #

Symptom: Processor fails to start with a shared library error.

Fix:

# RHEL/CentOS
sudo dnf install libxml2

# Ubuntu/Debian
sudo apt-get install libxml2

# Verify version (must be >= 2.9)
xmllint --version

Debug Mode #

For additional diagnostic output, set the log level to debug in your config:

logLevel: 'debug'

Or check logs with full verbosity:

journalctl -u xpro-processor -p debug -f

Getting Help #

• Free Edition: Open an issue at github.com/bluefunda/xpro-free
• Enterprise: Contact info@bluefunda.com for priority support