Troubleshooting Data Integration

Troubleshooting discusses some common problems you may encounter and suggest actions that will solve them.

Re-register if Replication agent is off for more than 30 days

If by any chance agent is turned off for more than 30 days, then re-registration would be required when the agent is started again. Following message indicates that re-registration is required

WARN 3296 — [ main] c.p.s.auth.impl.AgentRuntimeClientImpl : Existing token is invalid. Going to re-register

INFO 3296 — [ main] c.p.s.auth.impl.AgentRuntimeClientImpl : Verification Uri Complete: https://auth-qa.cloud.precisely.services/auth/realms/Precisely/device?user_code=BHJV-HUHM

Verification Uri will also be written to this path “/home/connect/.connect/agent/verification-uri”

To re-register a Replication agent
  1. Execute the following command to retrieve the verification from container logs:

    docker logs connect-agent-gateway | grep " Verification Uri Complete: "

    You need to authenticate using the operator access (minimum) by visiting the verification-uri in browser. After the authentication registration is complete, a successful agent registration message displays in the browser and the following messages are generated in the container console logs.

    INFO 4860 — [ main] c.p.s.auth.impl.AgentRuntimeClientImpl : Registered a new agent for tenantId: <tenantId> and for a product: <connect product name> with agent id: <agent id>

  2. Use the verification-uri to log into SaaS and enter your credentials to authenticate.

Errors generated in log while refreshing token

  • (error=invalid_grant, error_description=Session doesn't have required client)”
  • (error=invalid_grant, error_description=Stale token)
  • (error=invalid_grant, error_description=Session not active)
  • (error=invalid_grant, error_description=Maximum allowed refresh token reuse exceeded)
  • If the SaaSAgent Service responds with a 401 response
To refresh tokens
  1. Delete the .token file.
  2. Restart the agent.
  3. Execute the steps in Re-register if agent is off for more than 30 days.

Replication Agent ID is not found on the SaaS agent service

If an agent is not present in the precisely cloud agent service, the following error messages are generated in the container console logs. The agent stops.

WARN 16544 — [ main] c.p.s.auth.impl.AgentRuntimeClientImpl : Agent could not found in the cloud <Agent Id> for product name <Product Name>

INFO 11224 --- [extShutdownHook] o.s.b.w.e.tomcat.GracefulShutdown : Commencing graceful shutdown. Waiting for active requests to complete

INFO 11224 --- [tomcat-shutdown] o.s.b.w.e.tomcat.GracefulShutdown : Graceful shutdown complete

Metabase Errors

When you create, upgrade, or delete a metabase and problems occur that block the action from successfully completing, a Metabase Errors window opens showing all available SQL messages generated from the server system, including error messages. Use the error message details to help troubleshoot the problems before attempting the action again.

Note the following:
  • When you are creating a metabase and errors occur, any partially completed actions will be rolled back.
  • Scroll down to see any details too long to fit the Details field or drag the corner of the window to resize it.
  • To save the text of the error message, click Copy To Clipboard. You can paste the text into another application to share or archive.
  • To close the window, click Close. If you are creating a metabase, the New Metabase window remains open.
Types of Errors
  • When you upgrade and delete a metabase, the associated project must first be stopped. If you do not stop the project:
    • The error message will include details about how the kernel on the runtime server where you installed the software is running and must be stopped before you can proceed.
    • When there is data in the replication backlogs, you may see errors about losing transactions that have not yet been replicated.
  • When you upgrade or delete a metabase and the port number has changed for the connection associated with the metabase.
  • When you add a metabase and a metabase already exists for the data connection.
  • When you add a metabase and an invalid username and/or password are entered.

Relevant log files for Support

These are the logs and artifacts gather at the project/model level.

Name Description Filename Used for
Listener logs One set per listener/host. Rolls over at 10 MB by default, up to 10 files. kernel/<HostName>*.log Listener status. Summary of alerts across all models running on the listener. Needed to resolve host-wide/cross-project issues, resolve design-time issues, understand general environment, troubleshoot kernel startup.
Kernel logs One set per model/project per listener/host. Rolls over at 10 MB by default, up to 10 files. kernel/<ModelName>*.log Detailed logs for kernel (one model running on one host). Needed for full resolution of replication problems - runtime database connection issues, deployment/model update issues, data correctness issues, understanding of data volumes and performance.
Change Selector/Log Reader logs One set per Change Selector/Log Reader
  • DB2 on IBM i: Multi-member CS<n>LOG file. Also stored in RP_INFO metabase table. (Nice to have: RPCS400 job logs.)
  • DB2 on Z: SQData component logs such as SQDLOG.
  • DB2 LUW/UDB: CS log files.
  • N/A for other sources at this time
 Detailed logs for the capture mechanism. Needed for full resolution of transaction log capture issues, other system issues on the database source host, e.g. IBM i journaling, permissions accessing the transaction logs, etc. For non-DB2 sources, these are part of the kernel log, or are outside of the product (e.g. SQL Server agent)