Troubleshoot agent errors - Precisely Data Integrity Suite

Data Integrity Suite
Product
Spatial_Analytics
Data_Integration
Data_Enrichment
Data_Governance
Precisely_Data_Integrity_Suite
geo_addressing_1
Data_Observability
Data_Quality
dis_core_foundation
Services
Spatial Analytics
Data Integration
Data Enrichment
Data Governance
Geo Addressing
Data Observability
Data Quality
Core Foundation
ft:title
Data Integrity Suite
ft:locale
en-US
PublicationType
pt_product_guide
copyrightfirst
2000
copyrightlast
2026

Troubleshooting agent errors means finding and fixing problems with agents that handle tasks like data collection and monitoring. Key steps include checking error messages, reviewing settings, ensuring connectivity, and updating software. This helps keep everything running smoothly.

Services failed during installation

Symptoms:

  • One or more connectors (e.g., custom-jdbc-connector, snowflake-pipeline-connector, databricks-connector) fail during installation.

  • Error message similar to:

    ERROR::Operator - Installation continued despite failure in one module.

Resolution:

  1. Check connector status
    ./discli agent status
    This command looks for the services installed on the VM. If any service is missing, it was not deployed successfully.
  2. Restart the operator (recommended)
    ./discli agent restart operator

    Restarting the operator triggers re-deployment of failed services.

  3. (Optional) Update operator version, if the issue persists
    ./discli agent applyOperatorVersion --version=<latest>

Replication Engine test failed with a CDC error

If you test a Replication Engine and the test fails with a CDC‑related error, the message shown in the UI may not explain the root cause. In these cases, you should review the CDC runtime logs on the Agent.

Follow these steps if:

  • Replication Engine test fails during setup or validation
  • The error mentions CDC, capture, engine, or runtime
  • The engine shows Action Required without a clear fix

The Replication Engine depends on the CDC runtime on the Agent. If CDC fails, the engine test can fail even when the UI error is generic. CDC logs are stored on the Agent at: /precisely/connect/cdc/logs

How to view CDC logs

  1. Go to the CDC logs directory cd /precisely/connect/cdc/logs

  2. Lists available CDC log files ls

    You will typically see files like:

    LOCALHOST_51701.log

    LOCALHOST_51701_YYYY-MM-DD.N.log

    What these files mean:

    • LOCALHOST_<port>.log → current CDC runtime log
    • LOCALHOST_<port>_<date>.log → older (rotated) log'

  3. Opens the CDC log in read‑only mode so you can scroll and review errors safely.

    Helpful tips while viewing the log:

    • Use arrow keys to scroll
    • Type /error to search for errors
    • Press q to exit
  4. Look for any error or exception messages in the CDC log. If you’re unsure how to interpret an error or what it indicates, share the relevant log entries with Precisely Support for further analysis.

Failed agent installation

Installing the agent can sometimes encounter issues due to network issues, insufficient permissions, software conflicts, corrupt installation files, or unmet system requirements.

The agent CLI tool provides commands to manage the agent services, which are essential for ensuring optimal performance. Use these commands to diagnose and resolve common issues that can arise during the installation and runtime of the agent.

Table 1. Troubleshooting scenarios and solutions
Scenario Solution
To list all running agent services. ./discli agent status
To check agent communication with cloud services. If you get agent details logged in the console, then communication is good. If not, restart the operator service. ./discli agent details
If you observe one or more failed services, restart the operator service to start the failed services. ./discli agent restart operator
To retrieve the individual service logs. ./discli agent logs operator
If the machine restarts, start the agent again. ./discli agent start
To stop and start the agent service again.
Note: This will not fix the issues in the k3s service.
 Run the commands in this order:
  1. ./discli agent stop
  2. ./discli agent start
If disk is nearly full and disk space is low, Kubernetes services may stop automatically. Free up disk space and then restart the k3s agent using the steps above.
If the agent installation fails with an error relating to keytool/bc-fips, then follow the manual installation steps and retry the installation.
  1. Keytool installation: This command automatically downloads and installs keytool. However, if internet access is restricted or public URL downloads are blocked, manual installation is required as outlined below.
    • For RHEL (Red Hat Enterprise Linux): 
      sudo yum install -y java-1.8.0-openjdk-devel 
export JAVA_HOME=$(readlink -f /usr/bin/java | sed "s:bin/java::")
export PATH=$JAVA_HOME/bin:$PATH
    • For Ubuntu: 
      sudo apt install -y openjdk-11-jdk
export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
echo "export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64" >> ~/.bashrc
  2. BC FIPS JAR (bc-fips-2.0.0.jar) : The CLI attempts to automatically download and place the Bouncy Castle FIPS JAR in /precisely/agent/libs/. If this fails due to restricted internet access, follow the steps below to install it manually.
    • Manual Installation Steps:
      sudo mkdir -p /precisely/agent/libs/
sudo chmod -R 777 /precisely/agent/libs/
wget -O /precisely/agent/libs/bc-fips-2.0.0.jar https://repo1.maven.org/maven2/org/bouncycastle/bc-fips/2.0.0/bc-fips-2.0.0.jar

Log management

This section outlines the key log directories and commands used for monitoring and troubleshooting in the Data Integrity Suite.

  1. /logs/precisely/all - This directory contains all log files related to the application. It serves as a centralized location for monitoring and troubleshooting the application's performance and errors.

  2. /precisely/agent/install/logs - This directory contains installation logs for the agent. These logs provide detailed information about the installation process, helping to diagnose any issues that may arise during setup.

Log collection

Scenario: To ensure visibility into Agent behaviour and quickly resolve any issues, it's important to collect a complete diagnostic snapshot from the Agent host. This bundle includes log files, configuration metadata, and environment details essential for analysis. While traditional log management commands are designed for viewing, rotating, or archiving basic Agent log files, they may not be sufficient for troubleshooting complex issues. In such cases, a more comprehensive collection of data is needed for analysis.
Note: Reach out to Precisely Support (https://support.precisely.com/contact/) for troubleshooting any issues or concerns that may arise before attempting to self-resolve the concerns.

Solution: To address more complex scenarios, use the disdiag.sh utility. This tool gathers not only logs but also configuration details, metadata, and environmental information, offering a holistic view needed for advanced troubleshooting.

The utility is not included by default and must be downloaded manually. You can always find the latest version and knowledge base article: Creating Agent Diagnostic Bundles – Precisely KB

Steps to run the diagnostic utility

To generate a diagnostic bundle, you can generally follow these steps:

  • Sign in to the platform where the diagnostic tool will be used.

  • Download the diagnostic script or utility as described in the above knowledge base article.

  • Follow the instructions in the article to run the tool, as usage details may differ.

  • After execution, locate the generated diagnostic output file following guidance in the article.

Information to include when reporting an issue

When submitting an issue to support, please attach the generated diagnostic bundle and provide the following information:

  1. A clear description of the issue (including observed behavior and any error messages)

  2. Approximate time the issue occurred (please include relevant time zone)
  3. Relevant environment details (such as affected workspace, project, or instance)