Frequently asked questions

This page contains answers to some frequently asked questions for Cloud Data Ingestion.

How often can a CDI sync run?

Recurring syncs can run as often as every 5 minutes or as rarely as once per month. By default, the shortest interval you can set in the dashboard is 15 minutes, which helps manage your warehouse compute costs and request volume. To sync as often as every 5 minutes, contact Braze Support or your customer success manager. To sync as soon as your data changes, call the Trigger a sync endpoint. For more information, see How it works.

Why was I emailed: “Error in CDI Sync”?

This type of email usually means there’s an issue with your CDI setup. Here are some common issues and how to fix them:

CDI can’t access the data warehouse or table using your credentials

This could mean the credentials in CDI are incorrect or are misconfigured on the data warehouse. For more information, refer to the setup steps on your source page.

The table cannot be found

Try updating your integration with the correct database configuration or create matching resources on the data warehouse, such as database/table.

The catalog cannot be found

The catalog set up in the integration doesn’t exist in the Braze catalog. A catalog can be removed after the integration was set up. To resolve the issue, either update the integration to use a different catalog or create a new catalog that matches the catalog name in the integration.

Why was I emailed: “Row errors in your CDI sync”?

This type of email means that some of your data could not be processed during the sync. To find out the specific error, you can review the logs in Braze by going to CDI > Sync Log.

How do I fix “Time must be string in ISO8601 Format” in CDI setup?

This error means the event time value in your CDI payload is not in a supported datetime format.

For event and purchase payloads, format time as:

• An ISO 8601 string, or
• yyyy-MM-dd'T'HH:mm:ss:SSSZ

If time is omitted, Braze uses UPDATED_AT as the event time.

For full payload requirements, refer to Table setup for Cloud Data Ingestion.

How do I fix errors for Test Connection and support emails?

Test Connection runs on your data warehouse, so increasing warehouse capacity may improve its speed. Using a serverless SQL instance minimizes warm-up time and improves query throughput, but may result in slightly higher integration costs.

For error messages specific to your source, see the troubleshooting section on that source’s page:

How do I update my email alert preferences for CDI integrations?

Each integration has its own notification preference. Go to the CDI page and select the integration name you want to update. In the Notification preferences section you can update how you receive alerts regarding the selected integration.

Why am I seeing an “Incorrect Integration Object” error?

This error occurs when you try to update notification preferences for a CDI integration, and two or more workspaces have integrations pointing to the same cloud storage bucket or folder. Each cloud storage location can only be used by one integration at a time.

To resolve this:

1. Identify which other workspace has a CDI integration using the same storage location.
2. Remove or reconfigure the conflicting integration in the other workspace.
3. After removing the conflict, you can update notification preferences.

The error should no longer appear, and you should be able to update your notification preferences successfully. If you’re still experiencing issues, open a support ticket.

What happens if a future UPDATED_AT gets synced with an integration?

CDI uses UPDATED_AT to decide what data is new. After a future UPDATED_AT is synced, any data prior to that future date and time will not be processed. To fix this:

1. Correct UPDATED_AT.
2. Remove any old data that’s already synced with Braze
3. Create a new integration to process that table again.

Why doesn’t “Rows Synced” match the number in my warehouse?

CDI uses UPDATED_AT to decide which records to pick up during a sync. Check out this illustration to see how it works. At the beginning of a sync run, CDI queries your warehouse to get all records with UPDATED_AT later than the previously processed UPDATED_AT value. Records at the exact boundary timestamp may also be re-synced if new rows share that timestamp. Any record picked up at the time when the query executes is synced into Braze. Here are common cases when a record might not be synced:

• You’re adding records to the table with an UPDATED_AT value that has already been processed.
• You’re updating record values after they have been processed by a sync, but leaving UPDATED_AT unchanged.
• You’re adding or updating records while a sync is in progress. Depending on when the CDI query executes, there could be race conditions that lead to records not being picked up.

tip

To avoid these behaviors in the future, we recommend using monotonically increasing UPDATED_AT values and not updating the table during your scheduled sync run.

Do I need mostly distinct UPDATED_AT values for large CDI imports?

Yes. For high-volume runs (for example, more than approximately 10 million rows), make sure your source data has mostly distinct UPDATED_AT values. If too many rows share the same timestamp, CDI is more likely to re-select rows at boundary timestamps in later runs. This can increase duplicate syncs and data point consumption.

For more information about CDI boundary behavior, see Avoid resyncing rows with duplicate timestamps.

Where do I run these SQL checks?

Run the checks directly in your data warehouse SQL editor, against the same table or view used by your CDI integration:

• Snowflake: Projects > Worksheets (for more information, see Snowflake Worksheets)
• Redshift: Query Editor v2 (for more information, see Using Amazon Redshift Query Editor v2)
• BigQuery: BigQuery Studio SQL workspace (for more information, see BigQuery Studio introduction)
• Databricks: SQL editor (SQL warehouse) (for more information, see Databricks SQL editor)
• Fabric: SQL query editor

Use this process before enabling or scaling a large sync:

1. Identify the exact CDI source table or view and the sync window you want to validate.
2. Open your warehouse SQL editor and select the same database and schema used by CDI, then use a role with read access to the source table or view.
3. Run the distinct timestamp count query to measure how many distinct UPDATED_AT values exist in that window.
4. Run the query that groups by UPDATED_AT and counts rows to find timestamps with unusually high row counts.
5. If many rows share identical timestamps, adjust your ingestion process so consecutive batches use progressively newer UPDATED_AT values, or increase timestamp precision so rows are more distributed.
6. Re-run both queries until concentration is reduced, then launch or scale your sync.
7. After launch, monitor CDI > Sync Log for unexpected re-sync volume at boundary timestamps.

Use checks like these in your warehouse:

1
2
3
4
5
6
7

SELECT
  COUNT(*) AS total_rows,
  COUNT(DISTINCT UPDATED_AT) AS distinct_timestamps,
  ROUND(COUNT(*) * 1.0 / NULLIF(COUNT(DISTINCT UPDATED_AT), 0), 2) AS avg_rows_per_timestamp
FROM YOUR_CDI_SOURCE_TABLE
WHERE UPDATED_AT >= CAST('2026-04-01 00:00:00' AS TIMESTAMP)
  AND UPDATED_AT < CAST('2026-04-02 00:00:00' AS TIMESTAMP);

1
2
3
4
5
6
7
8
9

SELECT
  UPDATED_AT,
  COUNT(*) AS rows_at_timestamp
FROM YOUR_CDI_SOURCE_TABLE
WHERE UPDATED_AT >= CAST('2026-04-01 00:00:00' AS TIMESTAMP)
  AND UPDATED_AT < CAST('2026-04-02 00:00:00' AS TIMESTAMP)
GROUP BY UPDATED_AT
ORDER BY rows_at_timestamp DESC
LIMIT 20;

If your warehouse doesn’t support LIMIT (for example, Fabric), use an equivalent syntax such as TOP.

Why can a CDI sync with a small number of rows still take several minutes?

A CDI sync includes a fixed startup period before row processing begins. Because this startup time is similar across sync sizes, a small sync can still take several minutes and may appear slower in rows per minute. Total sync time still depends on your source query complexity, data shape, and available capacity in your data warehouse. For more information, see Cloud Data Ingestion sources.

During a sync, is the order preserved if multiple records share the same ID?

The processing order is not 100% predictable. For example, if there are multiple rows with the same EXTERNAL_ID in the table during a sync, we cannot guarantee which value will end up in the final profile. If you’re updating the same EXTERNAL_ID with different attributes in the payload column, all changes are reflected when the sync is completed.

Why are new users not being created from my CDI sync?

If your CDI integration has the Update existing users only option enabled, only users who already exist in Braze are updated, and new users are not created. This means that if a row in your sync table references an EXTERNAL_ID that doesn’t match any existing Braze user, that row is skipped.

To create new users through CDI, turn off the Update existing users only toggle in your integration settings. Go to Data Settings > Cloud Data Ingestion and select an integration.

What are the security measures for CDI?

Our measures

Braze has the following measures in place for CDI:

• All credentials are encrypted within our database, and only certain employees have authenticated access to them.
• We use encrypted connections to get data to customer warehouses.
• We make requests to the Braze API endpoints using the same API keys and TLS connections that we recommend our customers use.
• We regularly update our libraries and get any security patches.

Your measures

We recommend you and your team set up the following security measures on your side:

• Restrict credential access to the minimum required for CDI to operate. This is because we need to be able to run select (and count) on the specific tables and views.
• Restrict the IPs that can access the tables to the officially published Braze IPs. Each source page lists the IPs to allow for that source.