> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tetherdata.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Troubleshooting

> Resolve common integration issues

# 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:**

<Steps>
  <Step title="Verify Credentials">
    Check that the credentials entered in Tether match what's configured in the external service
  </Step>

  <Step title="Regenerate Credentials">
    If using API keys or access tokens, generate new ones from the external platform's settings
  </Step>

  <Step title="Recreate Integration">
    If credentials cannot be updated in place, delete the integration and create a new one with valid credentials
  </Step>

  <Step title="Check External Platform">
    Ensure the external platform account is active and the API access hasn't been revoked
  </Step>
</Steps>

### 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:**

<Steps>
  <Step title="Review Unmapped SKUs">
    Open the failed sync execution and check the error analysis section for the list of unmapped SKUs
  </Step>

  <Step title="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
  </Step>

  <Step title="Re-Sync">
    Trigger a manual sync to reprocess the previously failed records
  </Step>
</Steps>

### 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:**

<Steps>
  <Step title="Check Integration Status">
    Verify the integration is enabled on the integration detail page
  </Step>

  <Step title="Review Schedule">
    Check the cron expression and timezone are correct. Verify the "Next Sync" time is reasonable.
  </Step>

  <Step title="Check Last Sync">
    Review the most recent execution — did it complete successfully?
  </Step>

  <Step title="Verify Source Data">
    Confirm that new data exists in the external system within the expected date range
  </Step>

  <Step title="Trigger Manual Sync">
    Click **Trigger Sync** to force an immediate sync and check the results
  </Step>
</Steps>

### 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:**

| 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

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

| 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:

<Steps>
  <Step title="Contact Admin">
    Resetting sync state requires administrator access
  </Step>

  <Step title="Reset State">
    On the integration detail page, use the **Reset Sync State** action (admin only)
  </Step>

  <Step title="Confirm">
    This will delete all execution history for the integration
  </Step>

  <Step title="Monitor Full Sync">
    The next sync will perform a full data fetch. Monitor it closely for any mapping errors.
  </Step>
</Steps>

<Warning>
  Resetting sync state deletes all execution history and forces a full re-import. Use this only when necessary.
</Warning>

### After Extended Outage

<Steps>
  <Step title="Check Integration Status">
    Verify the integration is still enabled and credentials are valid
  </Step>

  <Step title="Review Missed Period">
    Check the last successful sync date to understand what was missed
  </Step>

  <Step title="Trigger Manual Sync">
    Run a manual sync to catch up on missed data
  </Step>

  <Step title="Verify Completeness">
    Check record counts and compare with the source system
  </Step>
</Steps>

## 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

<AccordionGroup>
  <Accordion title="Regular Monitoring">
    Check integrations regularly:

    * Review execution history for failures
    * Verify records are being fetched as expected
    * Check for increasing error counts
  </Accordion>

  <Accordion title="Keep Credentials Current">
    Maintain authentication:

    * Monitor for credential expiration
    * Use long-lived API tokens where possible
    * Document credential rotation procedures
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Maintain SKU Mappings">
    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
  </Accordion>
</AccordionGroup>

## 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

<CardGroup cols={2}>
  <Card title="Integration Setup" icon="plug" href="/integrations/setup">
    Configure integrations
  </Card>

  <Card title="Sync Sessions" icon="rotate" href="/integrations/sync-sessions">
    Monitor sync activity
  </Card>

  <Card title="Data Exports" icon="download" href="/tips/exports">
    Manual data handling
  </Card>

  <Card title="Channels" icon="shopping-cart" href="/channels/overview">
    Channel management
  </Card>
</CardGroup>