Common Issues

Quick solutions to frequently encountered problems.

Overview

This section covers common issues and their solutions:

Installation problems
Connection errors
Transformation failures
Performance issues

Quick Diagnostics

Run the diagnostic tool first:

tdk diagnostic --check-all

Issue Categories

Installation & Setup

Backend won’t start
Database migration failures
Missing dependencies

Connectivity

Database connection timeouts
Worker registration failures
Network problems

Transformations

Referential integrity violations
Type conversion errors
Memory errors

Performance

Slow workflow execution
High memory usage
Worker timeout errors

Common Error Messages

"Connection refused"

Cause: Cannot reach database or backend

Solution:

Check network connectivity
Verify firewall rules
Confirm service is running

"Out of memory"

Cause: Insufficient JVM heap

Solution:

export JAVA_OPTS="-Xmx8g"

"Foreign key constraint violation"

Cause: Referential integrity issue

Solution:

Check foreign key definitions
Verify parent tables are processed first
Use Virtual Foreign Keys

Getting Help

If you can’t find a solution:

Run diagnostics
Review FAQ
Contact support