> For the complete documentation index, see [llms.txt](https://doc.batch.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.batch.com/getting-started/features/customer-engagement-platform/profiles/cloud-sync/troubleshooting.md). # Troubleshooting ## 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 | Error message | Meaning / How to fix | | ------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `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. | Error message | Field | Applies to | How to fix | | --------------------------------------------------------------- | ----------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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. | Error message | Field | How to fix | | ----------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `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. | Error message | What it means | How to fix | | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `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: ``` Incoming request with IP/Token XXX is not allowed to access Snowflake ``` **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. {% hint style="info" %} If your security policy requires an IP allowlist, reach out to your CSM or Account Manager to discuss the options available for your setup. {% endhint %} ## Generic error | Error message | What it means | | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `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. {% hint style="info" %} 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. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://doc.batch.com/getting-started/features/customer-engagement-platform/profiles/cloud-sync/troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.