# Common Issues

> Source: https://docs.synthesized.io/tdk/latest/user_guide/080_troubleshooting/common_issues/
> For the complete documentation index, see [llms.txt](https://docs.synthesized.io/llms.txt).

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:

```shell
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**:

```shell
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](https://docs.synthesized.io/tdk/latest/user_guide/020_guides/managing_data_properties/virtual_foreign_keys)

## Getting Help

If you can’t find a solution:

1. Run [diagnostics](https://docs.synthesized.io/tdk/latest/user_guide/080_troubleshooting/common_issues/diagnostic)
2. Review [FAQ](https://docs.synthesized.io/tdk/latest/faq/synthesized-platform)
3. Contact support