SYNCED_TABLE_USER_ERROR error condition
Synced table pipeline user error.
ACCELERATED_SYNC_DATA_TOO_LARGE
Synced table <tableName> has too many large column values to use accelerated sync.
For a new synced table, disable accelerated sync when creating it from the UI.
For an existing synced table, contact Databricks support.
ACTIVE_ENDPOINTS_LIMIT
Instance: <instance>. The database project has exceeded its limit of concurrently active endpoints, so the synced table pipeline cannot connect. Detail: <detail>.
To resolve this issue, reduce the number of concurrently active endpoints, or increase the limit for your project.
ACTIVE_TIME_QUOTA_EXCEEDED
Instance: <instance>. The database project has exceeded its active time quota, so the synced table pipeline cannot connect. Detail: <detail>.
To resolve this issue, increase the active time quota for your project.
BRANCH_COMPUTE_TIME_EXCEEDED
Instance: <instance>. The database branch has exceeded its compute time, so the synced table pipeline cannot connect. Detail: <detail>.
To resolve this issue, increase the compute time available for this branch.
CHANGED_PRIMARY_KEY
The primary key columns specified for the synced table <destTableUcName> have been changed.
Specified primary key columns: (<primaryKeyColumns>). Current primary key columns: (<existingPrimaryKeyColumns>).
Changing the primary key columns of a synced table after it has been created is not supported.
To resolve this issue, either modify the synced table back to the original primary key columns, or create a new synced table and drop the existing one.
CHANGED_PRIMARY_KEY_COLUMN_TYPE
The data types of primary key columns <modifiedPkColumns> have been changed on synced table <destTableUcName>.
Changing the data types of primary key columns is not supported on a synced table after it has been created.
To resolve this issue, create a new synced table and drop the existing one.
CHARACTER_NOT_IN_REPERTOIRE
Instance: <instance>. Found invalid byte sequence in the source Delta table.
Detail: <detail>
This usually indicates the source Delta table contains characters that are not
compatible with the target database's encoding. One workaround is to convert the
source table to use BINARY TYPE, and then create a new synced table.
COLUMN_TYPE_CHANGE_NOT_SUPPORTED
Instance: <instance>. Changing the column type is currently not supported.
Source Delta table: <srcTableName>. Destination synced table: <destTableName>.
Column: <columnName>. Existing type: <existingType>. New type: <newType>.
To resolve this issue, consider one of the following options:
-
Perform a full refresh of the existing synced table.
-
Create a new synced table (which will pick up the new type)
COMPUTE_TIME_QUOTA_EXCEEDED
Instance: <instance>. The database account or project has exceeded its compute time quota, so the synced table pipeline cannot connect. Detail: <detail>.
To resolve this issue, increase the compute time quota for your account or project.
CONNECTION_ERROR
Instance: <instance>. Connection error. Detail: <detail>.
To resolve this issue, please ensure the database instance is running, not paused or stopped.
Restart the pipeline to retry.
DATABASE_DOES_NOT_EXIST
The destination database <databaseName> does not exist in lakebase instance <instance>. Please verify if the destination database exists.
DATABASE_ROLE_NOT_EXIST
Instance: <instance>. The Postgres role <roleName> that the synced table pipeline depends on does not exist. Detail: <detail>.
This typically occurs when the role was deleted from the database instance, for example after the identity was removed from the workspace.
To resolve this issue, recreate the Postgres role <roleName> on the database instance, or drop and recreate the synced table using an identity that still exists.
DATA_TRANSFER_QUOTA_EXCEEDED
Instance: <instance>. The database project has exceeded its data transfer quota, so the synced table pipeline cannot connect. Detail: <detail>.
To resolve this issue, increase the data transfer quota for your project.
DELTA_TRUNCATED_TRANSACTION_LOG
Detail: <detail>.
This indicates the delta table's transaction log has been truncated due to manual deletion or the log retention policy.
To resolve this issue, perform a full refresh of the synced table.
DEPENDENT_OBJECTS_STILL_EXIST
Instance: <instance>. Unable to drop a column because an existing
PostgreSQL object is still referring to the column. Detail: <detail>.
To resolve this issue, consider one of the following options:
-
Add the missing column(s) back to the source table with the same data type(s) as before.
-
Drop the dependent objects in PostgreSQL.
DESTINATION_NAME_NOT_A_TABLE
Instance: <instance>. Cannot create synced table <destTableUcName> because its destination name is already used by a <objectType> in the target database.
The synced table pipeline does not create or manage this object.
Drop or rename the existing <objectType>, or create the synced table with a different name, then retry.
DESTINATION_SCHEMA_ACCESS_ERROR
Instance: <instance>. The synced table pipeline does not have permission on the destination schema <schemaName>. Detail: <detail>.
The pipeline connects as the Postgres role <databaseUser>, which needs USAGE and CREATE on the destination schema to create and maintain the target table.
To resolve this issue, run: GRANT USAGE, CREATE ON SCHEMA <quotedSchemaName> TO <quotedDatabaseUser>; and then restart the pipeline.
DUPLICATE_PRIMARY_KEY_COLUMNS
Columns <duplicatedPkColumns> are specified multiple times in the primary key for the synced table <destTableUcName>.
To resolve this issue, remove the duplicate columns from the primary key so that each column appears only once.
ENDPOINT_DISABLED
Instance: <instance>. The target database instance has been disabled and cannot accept connections. Detail: <detail>.
This typically occurs when the instance has been stopped. A disabled instance cannot be started by a connection attempt.
To resolve this issue, re-enable or start the database instance, then restart the pipeline.
If the instance was stopped intentionally, pause or delete the synced table instead.
ENDPOINT_NOT_FOUND
Instance: <instance>. The target database endpoint could not be found or is not accessible. Detail: <detail>.
To resolve this issue, verify that the database instance exists and that the synced table is configured with the correct instance.
FOREIGN_KEY_CONSTRAINT_VIOLATION
Instance: <instance>. Foreign key constraint violation when syncing from source table:
<srcTableName>. Detail: <detail>
Creating foreign key constraints referencing sync tables is not supported. Please
drop the foreign key constraint and retry the sync.
INDEX_ROW_SIZE_EXCEEDED
Instance: <instance>. The primary key values in the source Delta table <srcTableName> are too large for the
PostgreSQL B-tree index. PostgreSQL limits index entries to approximately 2704 bytes across all primary key
columns combined. Detail: <detail>.
To resolve this issue, reduce the size of the data stored in the primary key columns, or use fewer or
shorter primary key columns.
INSUFFICIENT_INSTANCE_SPACE
Unable to perform synchronize table <tableName> into instance <instance> due to the database size.
Current instance usage: <instanceSize> bytes.
Estimated uncompressed table size: <estimatedLoadSize> bytes.
Instance size limit: <maxInstanceSize> bytes.
Please reduce the amount of data to synchronize, or drop some existing tables in the instance to free up space.
INVALID_ENDPOINT
Instance: <instance>. The database instance rejected the connection because the requested endpoint is not valid for this operation. Detail: <detail>.
This can occur when read-only connections are not allowed, or the requested compute does not exist.
To resolve this issue, verify the synced table's target instance and endpoint configuration, then restart the pipeline.
INVALID_SECONDARY_INDEX
Invalid secondary index configuration: <reason>.
INVALID_TABLE_NAME
Invalid table name <tableName>: expected a three-part name (catalog.schema.table).
INVALID_TYPE_OVERRIDE
Instance: <instance>. Invalid type override for column <columnName>: <reason>.
INVALID_VECTOR_DATA
Invalid vector data for column <columnName>: <reason>.
IP_NOT_ALLOWED
Instance: <instance>. The synced table pipeline's IP address is not allowed to connect to the database instance. Detail: <detail>.
To resolve this issue, update the database instance's IP allowlist to permit the connection.
LOCK_TIMEOUT
Instance: <instance>. Database: <databaseName>. The synced table pipeline could not acquire a lock within the configured timeout (<timeoutSeconds> seconds).
Detected <numBlockingTransactions> transaction(s) holding locks on the target table (max lock hold duration: <lockDurationSeconds> seconds).
User transactions are holding locks that are blocking the synced table pipeline from updating the target table.
For more information about the transactions involved in the error, check the Spark driver logs (search for '[LOCK TIMEOUT DIAGNOSTICS]').
To resolve this issue, find the connections with long-running transactions in the postgres instance using pg_stat_activity, and close those transactions (can also use pg_terminate_backend to terminate the connection if the connection isn't needed anymore).
To prevent this issue from happening in the future, consider the following options:
-
Make sure that your application either commits or rolls back the transaction.
-
Avoid long running transactions. Set auto_commit to on if the work in the application doesn't need to happen in a transaction.
-
Set idle_in_transaction_session_timeout on the database to automatically terminate idle transactions.
Example: ALTER DATABASE <databaseName> SET idle_in_transaction_session_timeout = '5min';
LOGICAL_SIZE_QUOTA_EXCEEDED
Instance: <instance>. The database project has exceeded its logical size quota, so the synced table pipeline cannot connect. Detail: <detail>.
To resolve this issue, increase the logical size quota for your project or reduce the amount of stored data.
MIS_CONFIGURED_PRIMARY_KEY
The provided primary keys for the source Delta table: <srcTableName> are not available in the source table.
Primary keys: <primaryKeys>. Available columns: <availableColumns>. Missing primary keys: <missingPkColumns>.
To resolve this issue, consider one of the following options:
-
Add the missing columns to the source table.
-
Create a new synced table with the correct primary key configuration.
NATIVE_LOGIN_BLOCKED
Instance: <instance>. Native (password) login is disabled for the database role used by the synced table pipeline. Detail: <detail>.
To resolve this issue, enable native login for the pipeline's database role, or reconfigure the role to use a supported authentication method.
NETWORK_BLOCKED
Instance: <instance>. The synced table pipeline is not allowed to connect to the database instance from its network. Detail: <detail>.
To resolve this issue, update the database instance's network access configuration to permit the connection.
PERMISSION_DENIED
Detail: <detail>.
Please verify if you have sufficient permissions.
PIPELINE_ROLE_NOT_EXIST
Instance: <instance>. The database writer role for synced table pipeline is missing. Detail: <detail>.
This typically occurs when the destination database has been dropped, which removes the pipeline's writer role.
To resolve this issue, verify that the destination database exists and has not been dropped.
If the database was intentionally dropped, delete the synced table and recreate it after recreating the database.
PRIMARY_KEY_CONSTRAINT_VIOLATION
Instance: <instance>. Duplicate rows detected based on primary key. Detail: <detail>
This likely indicates a misconfiguration of primary key columns.
Please verify that you are using the correct set of primary keys
from the source Delta table: <srcTableName>.
To resolve this issue, create a new synced table with the correct
primary key configuration.
QUOTA_EXCEEDED
Instance: <instance>. The target database account or project has exceeded its quota. Detail: <detail>.
To resolve this issue, reduce usage or upgrade the plan to increase the quota, then restart the pipeline.
REFRESH_WITH_FOREIGN_KEY
Instance: <instance>. Failed to refresh synced table <destTableName> because table
<childTableName> has a foreign key constraint referencing the synced table.
Refreshing the synced table is not supported when there are foreign key constraints
referencing it. Please drop the foreign key constraint and retry the refresh.
RELATION_SIZE_EXCEEDED
Unable to synchronize table <tableName> because a PostgreSQL relation exceeded the 32 TB per-relation limit.
Detail: <detail>.
PostgreSQL cannot store a single table, TOAST table, or index larger than 32 TB.
Reduce the amount of data in the source table, or split it across multiple synced tables.
REQUIRED_EXTENSION_NOT_INSTALLED
Instance: <instance>. The required PostgreSQL extension '<extension>' is not installed. Install it on the Lakebase instance before creating this sync.
ROLE_RESOLUTION_CONFLICT
The synced table's database role could not be resolved because its ownership conflicts with the pipeline run-as identity. Detail: <detail>.
Restore the pipeline's previous run-as identity or recreate the synced table with the intended run-as identity.
SCHEMA_BUILDER_NOT_ENABLED
Synced table schema customization (<features>) is not enabled for this workspace.
SCHEMA_DOES_NOT_EXIST
Detail: <detail>.
Please verify if the schema exists in Unity Catalog.
SOURCE_READ_ERROR
Failed to read from the source table <tableName>. Please verify if the source table can be read successfully through a SELECT query.
Detail: <detail>
SOURCE_SMART_CLONE_REQUIRED
The source materialized view <srcTableName> requires SmartClone to be enabled before it can be used as a synced table source. Run REPAIR TABLE <srcTableName> SYNC METADATA and retry.
SPARK_JOB_CANCELLED
Spark job is cancelled.
Detail: <detail>
SYSTEM_COLUMN_NAME_CONFLICT
Instance: <instance>. The source Delta table <srcTableName> contains a column whose name conflicts with a PostgreSQL system column name. Detail: <detail>.
PostgreSQL reserves certain column names (such as xmin, xmax, ctid, cmin, cmax, tableoid) for internal use.
To resolve this issue, rename the conflicting column in the source Delta table and recreate the synced table.
Or create a view with the conflicting columns excluded and sync the view instead.
SYSTEM_SCHEMA_ACCESS_ERROR
Instance: <instance>. The internal system schema (__db_system) is not accessible to the synced table pipeline. Detail: <detail>.
This can happen when the database was reset or the internal schema was dropped and recreated without proper permissions.
To resolve this issue, drop and recreate the synced table <destTableUcName>.
TABLE_DOES_NOT_EXIST
Detail: <detail>.
Please verify if the synced table exists in Unity Catalog.
TARGET_DATABASE_FULL
The target database <databaseName> space is full. Not able to continue to ingest.
TOO_MANY_CONNECTIONS
Too many open connections to the database instance: <instance>
Detail: <detail>.
Each table synchronization can use up to 16 connections to the database instance, which count toward the instance's connection limit.
To resolve this issue, try following options:
- Reduce the number of concurrent pipelines writing to the same database instance.
E.g., stagger the pipeline schedules.
- Reduce the number of concurrent connections from other workloads connecting to the same database instance.
UNSUPPORTED_COLUMN_TYPE
Instance: <instance>. Unsupported PostgreSQL column type: <columnType>.
UNTRANSLATABLE_CHARACTER
Instance: <instance>. Found untranslatable character in the source Delta table.
Detail: <detail>
This usually indicates the source Delta table contains characters that are not
compatible with the target database's encoding. One workaround is to convert the
source table to use BINARY TYPE, and then create a new synced table.
VPC_ENDPOINT_NOT_ALLOWED
Instance: <instance>. The synced table pipeline's VPC endpoint is not allowed to connect to the database instance. Detail: <detail>.
To resolve this issue, add the VPC endpoint to the database instance's allowed list.
WRITTEN_DATA_QUOTA_EXCEEDED
Instance: <instance>. The database project has exceeded its written data quota, so the synced table pipeline cannot connect. Detail: <detail>.
To resolve this issue, increase the written data quota for your project.