This documentation is available to agents as Markdown at https://docs.synthesized.io/tdk/latest/user_guide/080_troubleshooting/common_issues.md. For the complete documentation index, see llms.txt.

Common Issues

Fixes for the problems people hit most often, grouped by where they happen. Start with the run log or the service logs: the error message usually names the cause.

  • Run log: open the failed run in Governor, or read the output of the CLI.

  • Service logs: docker compose logs backend and docker compose logs worker, or kubectl logs deployment/governor-api and kubectl logs deployment/governor-worker.

Installation and sign-in

Problem What to do

backend isn’t healthy, or governor-api isn’t Running

Usually the connection to Governor’s own database. Check SPRING_DATASOURCE_URL, the user name and the password, and read the backend’s log. See Docker Compose or Kubernetes and OpenShift.

Sign-in fails on Governor’s DNS name, but works on localhost

Governor must be served over HTTPS from any address other than localhost. Put TLS termination in front of it. See TLS termination.

Port 80 is already in use

Stop the service using it, or change the frontend’s host port in docker-compose.yml, for example - "8080:80".

The frontend can’t use port 80 on Red Hat Enterprise Linux

SELinux blocks it. See the SELinux steps in Docker Compose.

Everyone is signed out after a restart

JWT_SECRET changed. Set the same value as before.

Stored data source passwords stop working after a restart

CREDENTIALS_ENCRYPTION_KEY changed. Set the previous key again; to change it, list the new key first and the old one after it, separated by ;.

For the demo, see Quick Start troubleshooting.

Licensing

Problem What to do

A data source is "not supported in the free version"

Governor or the CLI is running without a license key, in free mode. Set SYNTHESIZED_KEY, then restart the backend: docker compose up -d backend. For the CLI, see Set your license key.

A PostgreSQL, MySQL or MariaDB data source hits a limit of 20 tables or 100,000 rows

These are free mode’s limits. Add your license key.

The AWS Marketplace product doesn’t find its license

Set TDK_AWS_LICENSE_ENABLED=true, and give the task or pod the License Manager permissions. See AWS License Manager.

Connections

Problem What to do

"Connection refused", or the connection times out

Check the host and port in the JDBC URL, that the database is running, and that firewalls allow the connection. Runs connect from the worker or the CLI that runs them, so the database must be reachable from there, not only from your machine.

An SSL or TLS handshake error

See SSL certificate issues.

Authentication fails

Check the user name and password, and that the user isn’t locked. With a secret manager, check that it’s turned on and that the platform can read the secret. See Secret Managers.

"Permission denied" or "insufficient privileges"

Grant the platform’s user the permissions in Database Permissions: read on the input, and write on the output.

A Kerberos error

See Kerberos for database connections.

An error that names a JDBC URL parameter

Check the URL format for your database in Database Integrations. On the command line, put URLs that contain ;, & or ? in quotes.

Workers

Problem What to do

A run stays QUEUED, and no worker takes it

Check Administration > Workers: at least one worker must be connected. A worker takes a run only when both the input and the output data sources are in one of its worker groups, or the worker’s group is *. See Synthesized Workers.

A worker doesn’t appear under Administration > Workers

The worker can’t reach Governor’s gRPC port, 50055 by default. Check WORKER_SERVERHOST and WORKER_SERVERPORT, and the network route. Check that both sides agree on TLS: WORKER_USEPLAINTEXT on the worker, and the TLS settings on Governor.

A worker is rejected after you turn on mutual TLS

Its certificate must be signed by the CA Governor trusts, and Governor’s certificate must name the host the worker dials. See Worker–Governor mTLS.

Runs

Problem What to do

The run stops at a column that no rule matches

With safety_mode: STRICT, the default, every column needs a transformer, so the run stops instead of copying the column unchanged. Add a transformer or a rule for the column. Only switch to RELAXED if copying unmatched columns is acceptable: see Data Protection.

A foreign key constraint fails in the output

Check that the relationship is defined. Declare relationships the database doesn’t have as virtual foreign keys.

A unique or primary key constraint fails in the output

The output tables may already hold rows from an earlier run. Set table_truncation_mode: TRUNCATE to empty them first. For sequences and identity columns, see Auto-generated Types.

"Failed to claim sink. Synthesized Platform is already running."

Another run is writing to the same output, or an earlier run didn’t release its lock. See Database locking issues. Two runs at the same time need different output databases.

"Out of memory"

See Memory.

The run fails on one database’s data type or value

See Database-Specific Troubleshooting and Type Handling.

Collect diagnostics

To show support the structure of the input database without its data, run the diagnostic tool. It writes a summary to a CSV file:

tdk -iu '<jdbc url>' -iU <user> -ip <password> diagnostic -f report.csv

Related pages