Troubleshooting
This page lists the error messages you may encounter when creating a Cloud Sync in the Batch dashboard, what they mean, and how to fix them.
Form validation errors
These errors are detected before any connection attempt to your data source. They usually mean a required field is empty or has an invalid value.
General validation
Invalid or missing name.
The sync name is empty. Give your sync a name.
Name is too long.
The sync name exceeds 255 characters. Use a shorter name.
Invalid or missing source.
The source configuration is missing or malformed. Review the source settings.
Unsupported destination type.
The selected destination is not supported. Only profile attributes and profile events are supported.
Unsupported source type.
The selected source type is not supported.
Schedule must be an array.
The schedule configuration is missing or malformed.
Unsupported schedule type.
The selected schedule type is not supported.
Unsupported interval unit.
The selected interval unit is not supported.
Every value must be an integer.
The interval value must be a whole number.
Hour interval must be less than 24.
Hourly intervals must be below 24 hours. Use a daily schedule instead.
Source configuration fields
These errors appear directly under the field they relate to.
Invalid JSON for BigQuery credentials
Credentials
BigQuery
The service account key you pasted is not valid JSON. Paste the full, unmodified JSON key file.
Invalid or missing table name
Table
All sources
Enter the name of the table or view to sync.
Invalid or missing dataset ID
Dataset
BigQuery
Enter the BigQuery dataset ID containing your table.
Invalid or missing credentials
Credentials
BigQuery, Snowflake, Databricks
Provide the required credentials for the source.
credentialsJson must be a JSON string or an associative array
Credentials
BigQuery
The credentials are not in the expected JSON format. Paste the full service account JSON key.
Invalid or missing host
Host
ClickHouse, Snowflake, Redshift, Databricks, MSSQL
Enter the host of your database server.
Invalid or missing database
Database
ClickHouse, Redshift, Databricks, MSSQL
Enter the name of the database to connect to.
Invalid or missing username
Username
Redshift
Enter the database username.
Invalid or missing password
Credentials
Redshift
Enter the database password.
Invalid or missing HTTP path
HTTP path
Databricks
Enter the HTTP path of your Databricks SQL warehouse.
Invalid port
Port
ClickHouse, Redshift, MSSQL
Enter a valid port number.
Host must not be empty
Host
All except BigQuery
Enter the host of your database server.
Invalid host
Host
All except BigQuery
The host is not a valid hostname. Check for typos, spaces, or a protocol prefix (enter the hostname only, without https://).
Private or reserved IP addresses are not allowed
Host
All except BigQuery
The host points to a private or reserved IP address. Batch cannot reach private networks directly - use a publicly reachable host, or configure an SSH tunnel if available for your source.
Local network hostnames are not allowed
Host
All except BigQuery
Hostnames like .local or .internal are not reachable from Batch. Use a publicly resolvable hostname.
SSH tunnel fields (ClickHouse and MSSQL)
If you connect through an SSH tunnel, the tunnel configuration is validated as well.
Invalid or missing SSH tunnel host
SSH Tunnel Jump Server Host
Enter the host of your bastion / jump server.
SSH tunnel host must resolve to a public IP address
SSH Tunnel Jump Server Host
The bastion host resolves to a private IP address or does not resolve at all. The jump server must be publicly reachable.
Invalid SSH connection port
SSH Connection Port
Enter a valid SSH port (usually 22).
Invalid or missing SSH login username
SSH Login Username
Enter the username used to log in to the jump server.
Invalid or missing SSH private key
SSH Private Key
Paste the SSH private key (when using key authentication).
Invalid or missing SSH tunnel password
Password
Enter the SSH password (when using password authentication).
Connection errors
Once the form is valid, Batch tests the connection to your data source. If the test fails, a clear message is displayed under the relevant field, or globally when it does not relate to a specific field.
The table could not be found - check the table name, the database, its dataset or schema, and the configured user's permissions
The table, view, or schema does not exist, or the user cannot see it.
Verify the table name and its dataset/schema, and make sure the configured user has read access to it.
The table does not expose a compatible last_updated_at column
The cursor column used for incremental syncs is missing or has an incompatible type.
Make sure your table exposes a compatible last_updated_at column, as described in the setup guide of your source.
The Snowflake private key is invalid or uses an unsupported format - check the key and its passphrase
The Snowflake key-pair authentication failed.
Verify the private key format and the passphrase, and make sure the public key is registered on the Snowflake user.
The Snowflake role does not exist or is not granted to this user - check the role name and user permissions
The configured Snowflake role is unknown or not assigned to the user.
Check the role name spelling and grant the role to the configured user.
Microsoft Entra ID authentication failed - check the client ID, the client secret, and application consent
Authentication against Microsoft Entra ID was rejected.
Verify the client ID and client secret, and make sure admin consent was granted to the application.
The server requires Microsoft Entra ID authentication - provide a client ID and client secret instead of a username and password
The SQL server only accepts Entra ID authentication, but a username/password was provided.
Switch to Microsoft Entra ID authentication and provide a client ID and client secret.
The Databricks SQL warehouse could not be found - check the HTTP path
The HTTP path does not match an existing SQL warehouse.
Copy the HTTP path from your SQL warehouse's connection details in Databricks.
Databricks authentication failed - check the access token and workspace settings
The Databricks access token was rejected.
Generate a new access token and verify the workspace configuration.
The database could not be found or accessed - check the database name and the configured user's permissions
The database does not exist or the user cannot access it.
Verify the database name and the user's access rights.
Authentication failed - check the configured credentials and the database name
SQL Server login failed. On Microsoft Fabric, this can also mean the database does not exist.
Verify the username, password, and database name.
Authentication failed - check the configured credentials
The provided credentials were rejected by the source.
Verify the username, password, token, or key configured for the source.
The configured user is not allowed to read this source - check its database permissions
The user authenticated successfully but lacks read permissions.
Grant the user read access to the table and its schema/database.
A secure connection could not be established with the source - check the SSL and encryption settings
The SSL/TLS handshake with the source failed.
Verify the SSL and encryption settings on both the source and the sync configuration.
The source took too long to respond - check the host, port, credentials, network access, and firewall settings
The connection timed out - the host is unreachable or the connection is silently blocked.
Verify the host and port, then check for a network policy or IP allowlist blocking the connection (see below).
The source could not be reached - check the host, port, network access, and firewall settings
The connection was refused or the hostname could not be resolved.
Verify the host and port, check DNS resolution, then check for a network policy or IP allowlist blocking the connection (see below).
Network policies and IP allowlists
Symptom - The connection test times out or is refused, or a sync that used to work suddenly stops returning data. On Snowflake, your logs show an error similar to:
Cause - Your data source restricts inbound connections to an allowlist of IP addresses, for example a Snowflake Network Policy, a firewall rule, or a VPC restriction, and Batch's connections are not covered by it.
How to fix - Remove the IP restriction on the dedicated user Batch connects with, or disable the network policy temporarily to confirm this is the cause.
If your security policy requires an IP allowlist, reach out to your CSM or Account Manager to discuss the options available for your setup.
Generic error
The sync could not be created. Please review the fields and try again.
An unexpected technical error occurred (unrecognized source error, server error, or network issue). These errors are automatically reported to our team. Try again in a few minutes, and contact our support team if the problem persists.
Sync behaviour
I changed my table schema and the sync doesn't reflect it
Symptom - You add, rename, or change the type of a column in your source table or view. You re-run the sync, but Batch keeps using the previous schema.
Cause - Batch caches the schema of a sync's source. On an existing sync, a schema change can take up to 24 hours to be picked up. Re-triggering the same sync does not speed this up.
How to fix - Delete the sync and create a new one pointing at the same table. A newly created sync always reads the current schema immediately. You do not need to rename your table.
This matters most during implementation, when your table format may change several times a day. Deleting and recreating the sync is the expected workflow while you iterate. Once your schema is stable, you can leave the sync in place.
Last updated