# Installation Issues

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

Troubleshoot common problems during platform installation and setup.

## Backend Won’t Start

### Symptom

Backend container exits immediately or fails to start.

### Common Causes

1. **Metadata database not accessible**

Check logs:

```shell
docker compose logs backend | grep -i error
```

Solution: Verify PostgreSQL is running and accessible.

1. **Database credentials incorrect**

Solution: Check environment variables:

```shell
echo $SPRING_DATASOURCE_URL
echo $SPRING_DATASOURCE_USERNAME
```

1. **Port already in use**

Solution: Change port or stop conflicting service:

```shell
# Change port in docker-compose.yml
ports:
  - "8081:8080"  # Use 8081 instead
```

## Database Migration Fails

### Symptom

Error messages about schema migrations or Liquibase.

### Solution

1. **Clean database and restart**:

```shell
# Remove existing data
docker compose down -v

# Restart
docker compose up -d
```

1. **Manual migration check**:

```sql
-- Connect to metadata database
SELECT * FROM databasechangelog;
```

## Cannot Access Web UI

### Symptom

Browser shows "Connection refused" or "Unable to connect".

### Solutions

1. **Check backend is running**:

```shell
docker compose ps backend
```

1. **Verify port mapping**:

```shell
curl http://localhost:8080/actuator/health
```

1. **Check firewall**:

```shell
# Test from server
curl -I http://localhost:8080

# Check firewall rules
sudo iptables -L
```

## Worker Won’t Connect

### Symptom

Worker container starts but doesn’t appear in backend UI.

### Solutions

1. **Check BACKEND\_URL**:

```shell
docker compose logs worker | grep BACKEND_URL
```

1. **Verify network connectivity**:

```shell
docker compose exec worker curl http://backend:8080/actuator/health
```

1. **Check backend logs**:

```shell
docker compose logs backend | grep -i worker
```

## Insufficient Memory

### Symptom

"OutOfMemoryError" in logs.

### Solution

Increase memory allocation:

```yaml
# docker-compose.yml
services:
  backend:
    environment:
      JAVA_OPTS: "-Xmx4g"  # Increase to 4GB
```

## See Also

- [Post-Install Checklist](https://docs.synthesized.io/tdk/latest/user_guide/050_deployment_operations/deployment/post_install_checklist)
- [Reading Logs](https://docs.synthesized.io/tdk/latest/user_guide/080_troubleshooting/debugging/logs)
- [Connection Issues](https://docs.synthesized.io/tdk/latest/user_guide/080_troubleshooting/common_issues/connection)