Troubleshooting

This guide covers common sync errors, their root causes, and how to fix them. Use the sync run error details to identify the specific issue, then find the relevant section below.

Connection and Authentication Errors

Source Connection Failed

Error: Source connection failed: connection timed out or Source connection failed: authentication error

Cause: SignalSmith cannot connect to the source warehouse to execute the model query.

Solutions:

1. Navigate to Warehouses and check the source’s health status
2. Re-test the source connection — credentials may have been rotated
3. Verify network access — SignalSmith IPs may need to be re-allowlisted
4. For Snowflake: check if the warehouse is suspended (enable auto-resume)
5. For Databricks: check if the SQL warehouse or cluster is running

Destination Authentication Expired

Error: Destination authentication failed: invalid or expired token

Cause: The destination’s OAuth token or API key has expired.

Solutions:

1. Navigate to Destinations and click on the affected destination
2. Click Re-authenticate to refresh the OAuth token
3. For API key-based destinations, update the API key
4. Re-test the destination connection

Rate Limit Exceeded

Error: Rate limit exceeded: too many API requests or HTTP 429 Too Many Requests

Cause: The sync is sending requests faster than the destination API allows.

Solutions:

1. Reduce sync frequency — Increase the interval between runs
2. Stagger syncs — If multiple syncs hit the same destination, spread them out
3. Check destination plan — Some destinations have higher rate limits on premium plans
4. Contact destination support — Request a rate limit increase if needed

SignalSmith automatically retries rate-limited requests with exponential backoff, but sustained throttling can cause the run to exceed its timeout.

Model Query Errors

SQL Syntax Error

Error: Model query failed: syntax error at line X

Cause: The model’s SQL query has a syntax error. This can happen if the query was written for a different SQL dialect or if the source warehouse was changed.

Solutions:

1. Navigate to Models and open the affected model
2. Review the SQL at the reported line number
3. Fix the syntax error (check for dialect-specific functions)
4. Click Preview to validate the query
5. Save the model

Table or Column Not Found

Error: Model query failed: relation "X" does not exist or Column 'X' not found

Cause: The model references a table or column that no longer exists in the warehouse.

Solutions:

1. Check if the table was renamed, moved, or deleted in the warehouse
2. Verify the source’s database and schema settings are correct
3. Check if the warehouse user still has access to the table
4. Update the model SQL to reference the correct table/column names

Query Timeout

Error: Model query failed: query execution exceeded timeout (300s)

Cause: The model query takes too long to execute, typically due to large data volumes, missing indexes, or complex joins.

Solutions:

1. Add filters — Use WHERE clauses to reduce the data scanned (e.g., filter by date)
2. Remove unnecessary columns — Only SELECT the columns you actually need
3. Optimize joins — Ensure join columns are indexed in the warehouse
4. Use CTEs instead of subqueries — Some warehouses optimize CTEs better
5. Increase warehouse resources — For Snowflake, use a larger warehouse size; for Databricks, use a larger SQL warehouse

Field Mapping Errors

Required Field Not Mapped

Error: Required field 'LastName' is not mapped

Cause: The destination requires certain fields for record creation, and those fields are not mapped in the sync configuration.

Solutions:

1. Navigate to the sync’s field mapping configuration
2. Map the required field to an appropriate model column
3. If no model column matches, update the model SQL to include the required data:

-- Add a default value for a required field
SELECT
  email,
  first_name,
  COALESCE(last_name, 'Unknown') AS last_name  -- Ensure non-null
FROM customers

Data Type Mismatch

Error: Field 'Amount': expected number, got text "N/A"

Cause: The data type of the model column does not match the destination field’s expected type.

Solutions:

1. Clean the data in the model SQL:

-- Convert text to number, handling invalid values
SELECT
  email,
  CASE
    WHEN TRY_CAST(amount AS DECIMAL) IS NOT NULL
    THEN CAST(amount AS DECIMAL)
    ELSE 0
  END AS amount
FROM orders

2. Update the destination field type to accept the incoming data type
3. Filter out invalid rows in the model SQL:

SELECT email, amount
FROM orders
WHERE amount IS NOT NULL AND amount != 'N/A'

Invalid Email Format

Error: Invalid email format: "john@" or Email validation failed

Cause: The email column contains values that don’t pass the destination’s email validation.

Solutions:

1. Filter invalid emails in the model SQL:

SELECT email, name
FROM customers
WHERE email LIKE '%@%.%'  -- Basic email format check
  AND email NOT LIKE '%@%@%'  -- No double @
  AND LENGTH(email) > 5

2. Clean email data upstream in your warehouse

String Exceeds Max Length

Error: String value exceeds maximum length (255) for field 'Description'

Cause: A text column value is longer than the destination field’s maximum length.

Solutions:

1. Truncate in the model SQL:

SELECT
  email,
  LEFT(description, 255) AS description  -- Truncate to 255 chars
FROM customers

2. Increase the field’s max length in the destination (if configurable)

Row-Level Errors

Duplicate Records

Error: Duplicate value for unique field 'Email': john@example.com

Cause: The model returns multiple rows with the same identifier value that the destination treats as unique.

Solutions:

1. Add deduplication to the model SQL:

WITH ranked AS (
  SELECT *,
    ROW_NUMBER() OVER (PARTITION BY email ORDER BY updated_at DESC) AS rn
  FROM customers
)
SELECT email, name, phone
FROM ranked
WHERE rn = 1  -- Keep only the most recent record per email

2. Use a different identifier that is unique
3. Check for data quality issues in the source warehouse

NULL Primary Key

Error: Primary key column 'customer_id' contains NULL values

Cause: The model results include rows where the primary key column is NULL.

Solutions:

1. Filter out NULL primary keys in the model SQL:

SELECT customer_id, email, name
FROM customers
WHERE customer_id IS NOT NULL

2. Use a different column as the primary key
3. Fix the data quality issue in the source warehouse

Record Not Found for Update

Error: Record with identifier 'email=john@example.com' not found in destination

Cause: The sync is trying to update a record that doesn’t exist in the destination. This typically happens when the destination record was manually deleted.

Solutions:

1. This is usually self-correcting — the next run will create the record
2. If using upsert mode, this error should not occur (upsert creates if not found)
3. Check that the identifier mapping is correct

System-Level Errors

Out of Memory

Error: Sync run failed: out of memory processing model results

Cause: The model query returns too many rows or too much data for the sync engine to process.

Solutions:

1. Reduce row count — Add filters to the model SQL to limit the result set
2. Reduce column count — Remove unnecessary columns from the SELECT
3. Split into multiple syncs — Break a large sync into smaller syncs with filtered subsets
4. Contact support — For very large syncs (millions of rows), contact SignalSmith support for guidance

Destination API Error

Error: Destination API error: 500 Internal Server Error

Cause: The destination’s API is experiencing an outage or internal error.

Solutions:

1. Check the destination’s status page for known outages
2. Wait and retry — transient API errors often resolve on their own
3. SignalSmith automatically retries on 5xx errors with exponential backoff
4. If the issue persists, contact the destination’s support team

Sync Run Timeout

Error: Sync run exceeded maximum duration (2h) and was terminated

Cause: The sync run took too long to complete, usually due to a very large dataset or a slow destination API.

Solutions:

1. Optimize the model query to return fewer rows
2. Add incremental filters (e.g., only sync records updated in the last 7 days)
3. Split the sync into smaller batches
4. Check for destination API performance issues

Diagnostic Steps

When troubleshooting a sync issue, follow these steps:

1. Check the Run Details

Navigate to the sync’s Runs tab and click on the failed or errored run. Review:

• The overall run status and error message
• Row-level error details (if any)
• The run timeline to identify which phase failed

2. Verify the Source

• Check the source’s health status under Warehouses
• Re-test the connection
• Manually preview the model to verify the SQL executes correctly

3. Verify the Destination

• Check the destination’s health status under Destinations
• Re-authenticate if needed
• Verify the destination object and field configuration haven’t changed

4. Check the Field Mapping

• Review the sync’s field mapping for any unmapped required fields
• Verify data type compatibility between source and destination
• Check for new required fields added to the destination since the sync was created

5. Review the Data

• Preview the model results to check for data quality issues
• Look for NULL values in required fields
• Check for duplicates in identifier columns
• Verify data types match expectations

Getting Help

If you’ve followed the troubleshooting steps above and the issue persists:

1. Check the knowledge base — Search for your specific error message
2. Contact support — Include the sync ID, run ID, and error details
3. Review the API docs — Ensure your API usage matches the expected format

Next Steps

• Monitor sync runs for ongoing health
• Review sync modes to ensure you’re using the right mode
• Configure scheduling to optimize run frequency