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

# Troubleshooting Guide

> Solutions to common issues and how to resolve them quickly

<img src="https://placehold.co/800x400/5B47FB/ffffff?text=Troubleshooting" alt="Troubleshooting Guide" className="rounded-lg" />

## Quick Diagnostics

Before diving into specific issues, run through this checklist:

<Checklist>
  <Check title="App is installed and active" />

  <Check title="At least one zone is created and active" />

  <Check title="Zone has at least one active rate" />

  <Check title="Carrier service shows as active in Shopify settings" />

  <Check title="Test in Rate Sandbox works correctly" />
</Checklist>

## Common Issues

### No Shipping Rates at Checkout

<img src="https://placehold.co/600x300/f3f4f6/374151?text=No+Rates+Available" alt="No Rates Issue" className="rounded-lg" />

<Warning>
  This is the most common issue and usually has a simple fix.
</Warning>

<Steps>
  <Step title="Verify Zone Coverage">
    Check if the customer's address matches any zone:

    * Go to **Shipping Zones**
    * Review zone countries, states, and postal codes
    * Ensure the destination is included
  </Step>

  <Step title="Check Rate Status">
    Ensure rates are active:

    * Click **Manage Rates** on the zone
    * Verify at least one rate shows "Active"
    * Toggle inactive rates to active if needed
  </Step>

  <Step title="Test in Sandbox">
    Reproduce the issue:

    * Go to **Rate Sandbox**
    * Enter the exact address and cart details
    * Click **Calculate Rates**
    * Review any error messages
  </Step>

  <Step title="Verify Carrier Service">
    Check Shopify settings:

    * Go to Shopify Admin → Settings → Shipping
    * Look for "Smart Shipping" carrier service
    * Ensure it's active
  </Step>
</Steps>

### Wrong Shipping Rates

<AccordionGroup>
  <Accordion title="Rates Too High">
    **Possible Causes:**

    * Product group surcharges applied
    * Weight calculations incorrect
    * Min rate limits set too high

    **Solution:**

    1. Review product group modifiers
    2. Check product weights in Shopify
    3. Adjust rate configuration
  </Accordion>

  <Accordion title="Rates Too Low">
    **Possible Causes:**

    * Free shipping threshold triggered incorrectly
    * Percentage rates misconfigured
    * Max rate limits capping prices

    **Solution:**

    1. Verify threshold amounts
    2. Check percentage calculations
    3. Review max rate settings
  </Accordion>

  <Accordion title="Free Shipping Not Working">
    **Possible Causes:**

    * Threshold not met
    * Wrong calculation basis (subtotal vs total)
    * Rate conditions blocking free shipping

    **Solution:**

    1. Verify cart value meets threshold
    2. Check if taxes/discounts affect calculation
    3. Review rate conditions
  </Accordion>
</AccordionGroup>

### Performance Issues

<Tabs>
  <Tab title="Slow Calculations">
    **Symptoms:** Rates take > 3 seconds to appear

    **Solutions:**

    1. Reduce number of active rates (keep under 20 per zone)
    2. Simplify complex conditional rules
    3. Remove unused product groups
    4. Contact support for optimization help
  </Tab>

  <Tab title="Timeout Errors">
    **Symptoms:** "Unable to calculate shipping" message

    **Solutions:**

    1. Check system status page
    2. Reduce complexity of rate rules
    3. Verify internet connectivity
    4. Contact support if persistent
  </Tab>

  <Tab title="Inconsistent Results">
    **Symptoms:** Different rates for same cart

    **Solutions:**

    1. Clear browser cache
    2. Check for time-based rules
    3. Verify no A/B testing active
    4. Test in incognito/private mode
  </Tab>
</Tabs>

## Zone Issues

### Zone Not Matching

<Card>
  **Diagnostic Steps:**

  1. **Check Country Code Format**
     * Use 2-letter ISO codes (US not USA)
     * Verify spelling (GB not UK)
  2. **Verify State Format**
     * Use proper format: US-CA not California
     * Check abbreviations are correct
  3. **Test Postal Codes**
     * Remove spaces from postal codes
     * Verify wildcard patterns (902\* not 902\*\*)
  4. **Zone Priority**
     * Remember specific zones override general ones
     * Postal > State > Country priority
</Card>

### Multiple Zones Matching

<Info>
  When multiple zones match an address, Smart Shipping uses the most specific one. This is normal behavior.
</Info>

**Zone Priority Order:**

1. Exact postal code match
2. Wildcard postal code match
3. State/Province match
4. Country match
5. Catch-all zones (no restrictions)

## Product Group Problems

<AccordionGroup>
  <Accordion title="Products Not Grouped Correctly">
    **Check:**

    * Product tags in Shopify match group configuration
    * Product types are spelled correctly
    * Collections are properly assigned
    * SKU patterns match if using SKU rules
  </Accordion>

  <Accordion title="Group Modifiers Not Applying">
    **Verify:**

    * Group is active
    * Products are assigned to group
    * Modifier type (multiply vs add) is correct
    * Rate allows product group modifiers
  </Accordion>

  <Accordion title="Wrong Products in Group">
    **Review:**

    * Group matching rules
    * Product data in Shopify
    * Use Rate Sandbox to test specific products
  </Accordion>
</AccordionGroup>

## Testing Issues

### Rate Sandbox Not Working

<Steps>
  <Step title="Clear Form">
    Click "Clear" button and start fresh
  </Step>

  <Step title="Check Required Fields">
    * Product name
    * Weight (if using weight-based rates)
    * Price
    * Destination country
  </Step>

  <Step title="Verify Data Format">
    * Weight in correct units (lbs or kg)
    * Price without currency symbols
    * Valid country/state codes
  </Step>
</Steps>

### Live Checkout Different from Sandbox

**Possible Reasons:**

* Customer-specific discounts applied
* Shopify Scripts modifying rates
* Other apps interfering
* Cache showing old rates

**Solution:**

1. Test with a clean customer account
2. Disable Shopify Scripts temporarily
3. Check for conflicting apps
4. Clear all caches

## Integration Issues

### Conflicts with Other Apps

<Warning>
  Some apps may interfere with shipping calculations. Common conflicts include other shipping apps, discount apps, and checkout customizers.
</Warning>

**Resolution Steps:**

1. Temporarily disable other shipping apps
2. Test in Rate Sandbox
3. Re-enable apps one by one to identify conflict
4. Contact support for compatibility help

### Shopify Updates

After Shopify updates their platform:

<Checklist>
  <Check title="Verify carrier service still active" />

  <Check title="Test a few checkouts" />

  <Check title="Check for any new Shopify shipping settings" />

  <Check title="Review our changelog for updates" />
</Checklist>

## Error Messages

### Common Error Codes

| Error            | Meaning                   | Solution                          |
| ---------------- | ------------------------- | --------------------------------- |
| NO\_RATES\_FOUND | No rates match criteria   | Check zone and rate configuration |
| ZONE\_INACTIVE   | Matching zone is disabled | Activate the zone                 |
| INVALID\_ADDRESS | Address format issue      | Verify address details            |
| TIMEOUT          | Calculation took too long | Simplify rate rules               |
| SERVICE\_ERROR   | System issue              | Contact support                   |

## Quick Fixes

<CardGroup cols={2}>
  <Card title="Reset Everything" icon="refresh">
    1. Deactivate all zones
    2. Clear browser cache
    3. Reactivate zones one by one
    4. Test after each activation
  </Card>

  <Card title="Emergency Mode" icon="bolt">
    1. Create simple backup zone
    2. Single flat rate
    3. No conditions or modifiers
    4. Use while troubleshooting
  </Card>
</CardGroup>

## When to Contact Support

Contact support immediately if:

<Checklist>
  <Check title="Error persists after troubleshooting" />

  <Check title="Seeing system error messages" />

  <Check title="Rates suddenly stopped working" />

  <Check title="Performance degradation across all zones" />

  <Check title="Unable to access app dashboard" />
</Checklist>

**Before contacting support, gather:**

* Store URL
* Screenshot of error
* Steps to reproduce issue
* Recent changes made
* Rate Sandbox test results

## Prevention Tips

<AccordionGroup>
  <Accordion title="Regular Testing">
    * Test rates weekly
    * Check after any changes
    * Monitor customer complaints
    * Use Rate Sandbox before going live
  </Accordion>

  <Accordion title="Documentation">
    * Document your zone strategy
    * Keep notes on rate logic
    * Track changes made
    * Save working configurations
  </Accordion>

  <Accordion title="Gradual Changes">
    * Make one change at a time
    * Test after each change
    * Keep backup of working setup
    * Roll back if issues occur
  </Accordion>
</AccordionGroup>

<Note>
  **Need More Help?** If you can't resolve your issue, [contact our support team](/support/contact) with details about your problem.
</Note>