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
- Expired API access token
- Invalid credentials entered during setup
- Credentials revoked on the external platform
- Store URL changed or incorrect
Verify Credentials
Check that the credentials entered in Tether match what’s configured in the external service
Regenerate Credentials
If using API keys or access tokens, generate new ones from the external platform’s settings
Recreate Integration
If credentials cannot be updated in place, delete the integration and create a new one with valid credentials
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
- SKUs in the external system don’t have matching
external_idvalues in Tether - New products added to the external platform that haven’t been set up in Tether
- Naming mismatches between systems
Review Unmapped SKUs
Open the failed sync execution and check the error analysis section for the list of unmapped SKUs
Configure SKU Mappings
For each unmapped SKU, ensure the corresponding Tether SKU has the correct
external_id set to match the external system’s identifierUnmapped Channels
Symptoms:- Sync items fail with channel-related error messages
- Error analysis shows unmapped channel identifiers
- The external system references channels that don’t exist in Tether
- Channel names or IDs don’t match between systems
- Review the unmapped channel identifiers in the execution error analysis
- Create the missing channels in Tether or map existing channels correctly
- 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
- Integration is disabled
- Cron schedule not configured correctly
- No new data in the external system since last sync
- Credentials expired
Review Schedule
Check the cron expression and timezone are correct. Verify the “Next Sync” time is reasonable.
Verify Source Data
Confirm that new data exists in the external system within the expected date range
Partial Sync Failures
Symptoms:- Execution completes but statistics show a mix of success and failed records
- Some sync items have “PartialMapped” status
- Some records have mapping issues while others are fine
- External data contains inconsistencies
- Mixed valid and invalid records in the same batch
| Action | Description |
|---|---|
| Filter by Failed | Use the sync items filter to show only failed records |
| Review Errors | Check individual error messages for patterns |
| Fix Mappings | Resolve the most common mapping issues first |
| Re-Sync | Trigger a manual sync after fixes |
Platform-Specific Issues
Shopify
| Issue | Solution |
|---|---|
| Rate limit exceeded | Shopify GraphQL API has rate limits. Wait for the next scheduled sync, which will resume from where it left off |
| Orders not syncing | Verify the Admin API access token has the required read permissions for orders |
| SKU mismatches | Shopify SKUs are matched via external ID. Ensure Tether SKUs have the correct external_id set |
| Only paid orders syncing | By design, the Shopify integration filters orders by financial status (paid, partially refunded) |
TrackStar (Warehouse Management)
| Issue | Solution |
|---|---|
| Inventory not updating | Verify the integration has the “Warehouse Inventory” capability enabled |
| Connection failed | Check TrackStar API credentials are valid |
| Missing warehouses | Ensure warehouses are configured in both TrackStar and Tether |
BigQuery / Redshift (Data Warehouses)
| Issue | Solution |
|---|---|
| Query errors | Verify database connection credentials and permissions |
| No data returned | Check that the configured queries or tables contain data |
| Schema changes | If the source schema changed, review and update the integration configuration |
Diagnostic Steps
Step 1: Check Integration Status
- Go to Integrations in the sidebar
- Verify the integration is Enabled
- Check the Last Sync and Next Sync times
Step 2: Review Recent Executions
- Click on the integration to open its detail page
- Review the sync execution history
- Look for failed executions or executions with high failure counts
Step 3: Inspect Failed Execution
- Click on a failed execution
- Review the Statistics (success/failed/skipped counts)
- Check if it was a Dry Run (dry runs don’t save data)
- Filter sync items by “Failed” status
- Review error messages for patterns
Step 4: Check Error Analysis
- In the execution detail page, look at the aggregate error analysis
- Note any unmapped SKUs or channels
- Review the top error messages
Step 5: Trigger Manual Sync
- Go back to the integration detail page
- Click Trigger Sync
- Monitor the new execution for results
Error Message Reference
| Error Pattern | Meaning | Action |
|---|---|---|
| Unmapped SKU | SKU from external system not found in Tether | Add external_id to the matching Tether SKU |
| Unmapped Channel | Channel identifier not recognized | Create or map the channel in Tether |
| Authentication failed | Invalid or expired credentials | Update credentials or recreate integration |
| Rate limited | Too many API requests | Wait for next scheduled sync |
| Connection timeout | Network or platform issue | Retry with manual sync |
Recovery Procedures
Reset Sync State
If sync data becomes corrupted or you need to re-import all data:After Extended Outage
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
Regular Monitoring
Regular Monitoring
Check integrations regularly:
- Review execution history for failures
- Verify records are being fetched as expected
- Check for increasing error counts
Keep Credentials Current
Keep Credentials Current
Maintain authentication:
- Monitor for credential expiration
- Use long-lived API tokens where possible
- Document credential rotation procedures
Test with Dry Run
Test with Dry Run
Before making changes:
- Use dry run mode to validate configuration changes
- Review results before enabling live sync
- Check for new unmapped SKUs or channels
Maintain SKU Mappings
Maintain SKU Mappings
Keep external ID mappings up to date:
- Add
external_idvalues 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
| Information | Why Needed |
|---|---|
| Integration name and service | Identify the integration |
| Execution ID | Locate the specific sync run |
| Error messages | Understand the issue |
| When it started | Timeline context |
| Steps already tried | Avoid duplication |
Next Steps
Integration Setup
Configure integrations
Sync Sessions
Monitor sync activity
Data Exports
Manual data handling
Channels
Channel management