Skip to main content

​
Integration Troubleshooting

This guide helps you identify and resolve common integration issues.

​
Common Issues

​
Authentication Errors

Symptoms:
  • Sync execution fails immediately
  • Error message referencing credentials or authentication
  • No records fetched
Causes:
  • Expired API access token
  • Invalid credentials entered during setup
  • Credentials revoked on the external platform
  • Store URL changed or incorrect
Solutions:
1

Verify Credentials

Check that the credentials entered in Tether match what’s configured in the external service
2

Regenerate Credentials

If using API keys or access tokens, generate new ones from the external platform’s settings
3

Recreate Integration

If credentials cannot be updated in place, delete the integration and create a new one with valid credentials
4

Check External Platform

Ensure the external platform account is active and the API access hasn’t been revoked

​
Unmapped SKUs

Symptoms:
  • Sync executions complete but with many “Failed” sync items
  • Error messages referencing unmapped or unrecognized SKU identifiers
  • Aggregate error analysis shows a list of unmapped SKU IDs
Causes:
  • SKUs in the external system don’t have matching external_id values in Tether
  • New products added to the external platform that haven’t been set up in Tether
  • Naming mismatches between systems
Solutions:
1

Review Unmapped SKUs

Open the failed sync execution and check the error analysis section for the list of unmapped SKUs
2

Configure SKU Mappings

For each unmapped SKU, ensure the corresponding Tether SKU has the correct external_id set to match the external system’s identifier
3

Re-Sync

Trigger a manual sync to reprocess the previously failed records

​
Unmapped Channels

Symptoms:
  • Sync items fail with channel-related error messages
  • Error analysis shows unmapped channel identifiers
Causes:
  • The external system references channels that don’t exist in Tether
  • Channel names or IDs don’t match between systems
Solutions:
  1. Review the unmapped channel identifiers in the execution error analysis
  2. Create the missing channels in Tether or map existing channels correctly
  3. Trigger a manual sync to reprocess

​
Data Not Syncing

Symptoms:
  • No new sync executions appearing
  • Records fetched count is zero
  • Expected data not showing up in Tether
Causes:
  • Integration is disabled
  • Cron schedule not configured correctly
  • No new data in the external system since last sync
  • Credentials expired
Solutions:
1

Check Integration Status

Verify the integration is enabled on the integration detail page
2

Review Schedule

Check the cron expression and timezone are correct. Verify the “Next Sync” time is reasonable.
3

Check Last Sync

Review the most recent execution — did it complete successfully?
4

Verify Source Data

Confirm that new data exists in the external system within the expected date range
5

Trigger Manual Sync

Click Trigger Sync to force an immediate sync and check the results

​
Partial Sync Failures

Symptoms:
  • Execution completes but statistics show a mix of success and failed records
  • Some sync items have “PartialMapped” status
Causes:
  • Some records have mapping issues while others are fine
  • External data contains inconsistencies
  • Mixed valid and invalid records in the same batch
Solutions:

​
Platform-Specific Issues

​
Shopify

​
TrackStar (Warehouse Management)

​
BigQuery / Redshift (Data Warehouses)

​
Diagnostic Steps

​
Step 1: Check Integration Status

  1. Go to Integrations in the sidebar
  2. Verify the integration is Enabled
  3. Check the Last Sync and Next Sync times

​
Step 2: Review Recent Executions

  1. Click on the integration to open its detail page
  2. Review the sync execution history
  3. Look for failed executions or executions with high failure counts

​
Step 3: Inspect Failed Execution

  1. Click on a failed execution
  2. Review the Statistics (success/failed/skipped counts)
  3. Check if it was a Dry Run (dry runs don’t save data)
  4. Filter sync items by “Failed” status
  5. Review error messages for patterns

​
Step 4: Check Error Analysis

  1. In the execution detail page, look at the aggregate error analysis
  2. Note any unmapped SKUs or channels
  3. Review the top error messages

​
Step 5: Trigger Manual Sync

  1. Go back to the integration detail page
  2. Click Trigger Sync
  3. Monitor the new execution for results

​
Error Message Reference

​
Recovery Procedures

​
Reset Sync State

If sync data becomes corrupted or you need to re-import all data:
1

Contact Admin

Resetting sync state requires administrator access
2

Reset State

On the integration detail page, use the Reset Sync State action (admin only)
3

Confirm

This will delete all execution history for the integration
4

Monitor Full Sync

The next sync will perform a full data fetch. Monitor it closely for any mapping errors.
Resetting sync state deletes all execution history and forces a full re-import. Use this only when necessary.

​
After Extended Outage

1

Check Integration Status

Verify the integration is still enabled and credentials are valid
2

Review Missed Period

Check the last successful sync date to understand what was missed
3

Trigger Manual Sync

Run a manual sync to catch up on missed data
4

Verify Completeness

Check record counts and compare with the source system

​
Dry Run Troubleshooting

If you’re using dry run mode to test an integration:
  • Sync executions are marked with a Dry Run badge
  • No data is saved to Tether, so you can safely test mappings
  • Review sync items to see which records would succeed or fail
  • Fix any mapping issues before disabling dry run mode

​
Preventing Issues

​
Best Practices

Check integrations regularly:
  • Review execution history for failures
  • Verify records are being fetched as expected
  • Check for increasing error counts
Maintain authentication:
  • Monitor for credential expiration
  • Use long-lived API tokens where possible
  • Document credential rotation procedures
Before making changes:
  • Use dry run mode to validate configuration changes
  • Review results before enabling live sync
  • Check for new unmapped SKUs or channels
Keep external ID mappings up to date:
  • Add external_id values when creating new SKUs
  • Update mappings when external system IDs change
  • Periodically review unmapped SKU reports

​
When to Contact Support

Contact Tether support when:
  • Issue persists after following troubleshooting steps
  • Error messages are unclear or unexpected
  • Data corruption is suspected
  • You need help with complex integration configurations

​
Information to Provide

​
Next Steps

Integration Setup

Configure integrations

Sync Sessions

Monitor sync activity

Data Exports

Manual data handling

Channels

Channel management