---
title: "Troubleshooting"
description: "Solutions to common issues"
---

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

# Troubleshooting

Solutions to common issues you might encounter while using FirearmCart. Find your issue below and follow the steps to resolve it.

---

## Store & Access Issues

### Can't Log In

**Symptoms:** Unable to access your FirearmCart admin

**Solutions:**

1. **Verify credentials**
   - Check email address is correct
   - Check caps lock isn't on
   - Try typing password in a text editor first

2. **Reset password**
   - Click "Forgot password" on login page
   - Check email (including spam folder)
   - Follow reset link

3. **Two-factor authentication issues**
   - Verify device time is synced
   - Use backup codes if available
   - Contact support if locked out

4. **Too many attempts**
   - Login is limited to 5 attempts per minute
   - Wait a minute and try again
   - Contact support if you still can't get in

### Store Not Loading

**Symptoms:** Your storefront shows error or blank page

**Solutions:**

| Issue | Solution |
|-------|----------|
| **Blank page** | Check theme is published |
| **Error message** | Note error, check logs |
| **Slow loading** | Check for large images |
| **SSL error** | Verify domain settings |

**Steps to diagnose:**

1. Try accessing in incognito/private mode
2. Try a different browser
3. Check if admin panel loads
4. Review recent changes made
5. Contact support with details

### Admin Panel Slow

**Symptoms:** FirearmCart admin is loading slowly

**Solutions:**

1. **Browser issues**
   - Clear browser cache
   - Disable browser extensions
   - Try different browser

2. **Network issues**
   - Check internet connection
   - Try different network
   - Verify not using VPN that slows connection

3. **System issues**
   - Check the status page at [status.firearmcart.com](https://status.firearmcart.com)
   - Report if issue persists

---

## Product Issues

### Products Not Appearing on Store

**Symptoms:** Products visible in admin but not on storefront

**Solutions:**

| Check | Solution |
|-------|----------|
| **Status** | Ensure product status is **Active**, not Draft |
| **Inventory** | Verify stock quantity > 0 if "Track quantity" is on |
| **Out of stock** | Enable "Continue selling when out of stock" to keep it listed at zero stock |
| **Collections** | Ensure product is in a visible collection |
| **Pricing** | Confirm price is set |

**Steps:**

1. Open the product in admin
2. Set **Status** to Active
3. Check inventory settings
4. Save and refresh the storefront

### Images Not Uploading

**Symptoms:** Product images fail to upload

**Solutions:**

| Issue | Solution |
|-------|----------|
| **File too large** | Product and variant images must be under 5MB. Files uploaded to the file library and collection galleries can be up to 10MB. Store logo, checkout logo, and favicon must be under 1MB |
| **Wrong format** | Use a standard image format such as JPEG, PNG, GIF, or WebP |
| **Slow connection** | Wait for upload to complete |
| **Browser issue** | Try different browser |

**Best practices:**
- Optimize images before upload
- Use JPEG for photos (smaller size)
- Use PNG for graphics with transparency
- Recommended: 2048x2048px maximum

### Inventory Not Syncing

**Symptoms:** Inventory levels not updating from distributor

**Solutions:**

1. **Check plugin status**
   - Navigate to **Plugins** and open the distributor
   - Verify the connection is active
   - Check last sync timestamp

2. **Re-sync manually**
   - Click "Sync now" on integration
   - Wait for sync to complete
   - Check for error messages

3. **Verify credentials**
   - API credentials may have expired
   - Re-enter credentials
   - Test connection

4. **Check distributor status**
   - Distributor API may be down
   - Check distributor's status page
   - Try again later

Remember that distributor catalogs sync on a schedule set by your plan — every 12 hours on Starter, every 6 hours on Growth, and hourly on Pro — so a change at the distributor won't appear instantly.

### Product Variants Not Working

**Symptoms:** Variants not displaying or pricing incorrectly

**Solutions:**

1. **Check variant configuration**
   - Each variant needs price set
   - Each variant needs inventory
   - Options must be properly defined

2. **Display issues**
   - Check theme supports variants
   - Clear cache
   - Test in incognito mode

---

## Order Issues

### Payment Not Processing

**Symptoms:** Customers unable to complete checkout

**Solutions:**

| Error | Cause | Solution |
|-------|-------|----------|
| **Card declined** | Customer's bank issue | Customer contacts bank |
| **Gateway error** | Processor connection issue | Check API credentials |
| **Timeout** | Slow connection | Customer retry |
| **Not configured** | Missing payment setup | Complete payment setup |

**Steps to diagnose:**

1. Check Settings > Payments for status
2. Verify payment processor connection
3. Review recent transactions for patterns
4. Check processor dashboard for errors
5. Test with a small transaction

### Order Stuck in Processing

**Symptoms:** Order not moving to next status

**Solutions:**

1. **Payment pending**
   - Check if payment completed
   - View transaction in processor dashboard
   - Mark paid manually if confirmed

2. **FFL selection needed**
   - Firearm order awaiting FFL
   - Contact customer for FFL selection
   - Customer selects FFL in their account

3. **Manual review required**
   - Check order flags
   - Review for fraud indicators
   - Approve or cancel as appropriate

### Can't Fulfill Order

**Symptoms:** Fulfill button not working or error when fulfilling

**Solutions:**

| Issue | Solution |
|-------|----------|
| **No items to fulfill** | Already fulfilled |
| **Missing shipping info** | Edit order, add address |
| **Carrier error** | Check shipping integration |
| **Out of stock** | Restock or cancel items |

### Customer Didn't Receive Order Confirmation

**Symptoms:** Customer says they didn't get email

**Solutions:**

1. **Verify email address**
   - Check for typos in order
   - Confirm email is correct

2. **Check spam folder**
   - Ask customer to check spam/junk
   - Add your domain to safe senders

3. **Resend the confirmation**
   - Open the order
   - Open the actions menu and choose **Resend Emails > Order Confirmation**
   - Confirm the email was sent

   Refund confirmations and tracking emails can be resent the same way.

4. **Email deliverability**
   - Check email settings
   - Verify sender domain
   - Review email logs

---

## Payment Issues

### Refund Failed

**Symptoms:** Error when processing refund

**Solutions:**

| Error | Cause | Solution |
|-------|-------|----------|
| **Exceeds original** | Refunding more than paid | Check amount |
| **Already refunded** | Duplicate refund attempt | Review refund history |
| **Processor error** | Gateway issue | Retry or check processor |
| **Card expired** | Original card no longer valid | Issue store credit |

**Steps:**

1. Verify refund amount is correct
2. Check previous refunds on order
3. Confirm with payment processor
4. Try again or use alternative method

### Payment Processor Disconnected

**Symptoms:** Payments failing, processor shows disconnected

**Solutions:**

1. **Re-authenticate**
   - Navigate to Settings > Payments
   - Click on processor
   - Re-enter credentials
   - Test connection

2. **Check credentials**
   - Verify API key hasn't expired
   - Confirm credentials match processor dashboard
   - Generate new keys if needed

3. **Processor account issue**
   - Check processor dashboard for alerts
   - Verify account is in good standing
   - Contact processor support
### Transaction Fees Seem Wrong

**Symptoms:** Fees higher than expected

**Solutions:**

1. **Review rate schedule**
   - Check contract with processor
   - Verify rate tier
   - International cards often higher

2. **Check transaction types**
   - Card-present vs card-not-present
   - Debit vs credit
   - Rewards cards

3. **Contact processor**
   - Request fee breakdown
   - Ask about rate optimization
   - Review recent statements

---

## Shipping Issues

### Shipping Rates Not Showing

**Symptoms:** Checkout shows no shipping options

**Solutions:**

| Check | Solution |
|-------|----------|
| **Shipping zones** | Ensure customer's location is covered |
| **Rates configured** | Add rates to zones |
| **Product weight** | Ensure products have weights |
| **Shipping profiles** | Check profile assignments |

**Steps:**

1. Navigate to Settings > Shipping
2. Review shipping zones
3. Confirm customer's location is in a zone
4. Check rates exist for that zone
5. Verify products have shipping weights

### Wrong Shipping Rates

**Symptoms:** Rates too high or too low

**Solutions:**

1. **Check product weights**
   - Open affected products
   - Verify weight is accurate
   - Update if incorrect

2. **Check product dimensions**
   - Dimensional weight may apply
   - Update package dimensions
   - Use actual dimensions

3. **Review rate configuration**
   - Check rate calculation method
   - Verify carrier rates are current
   - Test with known dimensions

### Printify Orders or Catalog Not Syncing

**Symptoms:** Shop products missing from **Plugins > Printify**, or orders not appearing in Printify

**Solutions:**

1. **Check the connection**
   - Open **Plugins > Printify**
   - Use **Test Connection**
   - Printify tokens expire after one year — paste a new token from the marketplace if the current one is rejected

2. **Check the shop catalog**
   - FirearmCart only lists products already published in the connected Printify shop
   - Use **Resync now** from the **Sync info** (ⓘ) menu

3. **Check fulfillment**
   - Confirm the fulfillment is routed to Printify and has been processed
   - If **Hold production** is on, the order is in Printify on hold until you release it

4. **Check tracking webhooks**
   - Click **Re-register webhooks**
   - Tracking is also polled every four hours if a webhook is missed

See [Printify](/integrations/printify) for the full setup and troubleshooting guide.

### ShipStation Not Syncing Orders

**Symptoms:** Orders not appearing in ShipStation

**Solutions:**

1. **Check connection status**
   - Navigate to **Plugins > ShipStation**
   - Verify the connection is active

2. **Check sync settings**
   - Verify order types selected
   - Check status filters
   - Confirm store is selected

3. **Re-authorize**
   - Disconnect ShipStation
   - Reconnect with fresh authorization
   - Test sync

4. **Check ShipStation**
   - Verify store appears in ShipStation
   - Check ShipStation logs
   - Contact ShipStation support

---

## Theme Issues

### Theme Changes Not Appearing

**Symptoms:** Changes made but not visible on storefront

**Solutions:**

| Issue | Solution |
|-------|----------|
| **Not published** | Publish the theme, or make sure you edited the published one |
| **Storefront cache** | Clear the theme cache, or turn on Developer Mode to bypass it |
| **Browser cache** | Clear your browser cache |
| **Wrong theme** | Verify you're editing the live theme |

**Steps:**

1. Confirm you're editing the live theme
2. Click "Save" after making changes
3. Clear the theme cache from **Store > My Store**, or enable Developer Mode
4. Clear browser cache (Ctrl+Shift+Delete)
5. View in incognito mode

### Visual Editor Not Loading

**Symptoms:** Editor shows blank or error

**Solutions:**

1. **Browser issues**
   - Clear cache and cookies
   - Disable browser extensions
   - Try different browser

2. **Theme issues**
   - Check theme for Liquid errors
   - Revert recent code changes
   - Reset to default theme temporarily

3. **Connection issues**
   - Check internet connection
   - Try different network
   - Retry in a few minutes

### Developer Mode Turned Itself Off

**Symptoms:** Storefront edits stopped appearing immediately again

**What's happening:**

Developer Mode bypasses the storefront cache for a set window — 30 minutes, 2 hours, or 8 hours — and switches off automatically when that window ends. **Your code changes are not affected.** Nothing is reverted, unpublished, or lost; the storefront simply goes back to serving cached pages.

**Solutions:**

1. Re-enable Developer Mode from **Store > My Store** and pick a longer window
2. Or clear the theme cache once, instead of leaving the bypass on

### Recovering a Theme File

**Symptoms:** A code change broke something and you want the previous version back

**Solutions:**

Every save in the code editor is versioned. Open the file, view its version history, and restore an earlier version.

---

## Integration Issues

### Distributor Integration Not Working

**Symptoms:** Products not syncing from Lipseys/RSR/MGE

**Solutions:**

1. **Check credentials**
   - Verify API credentials are current (MGE uses FTP username/password + dealer number)
   - Some credentials expire periodically
   - Generate new credentials if needed
   - MGE acknowledgements are not instant — check the fulfillment timeline before retrying

2. **Check permissions**
   - Verify API access is enabled on distributor side
   - Confirm account has necessary permissions
   - Contact distributor for access issues

3. **Check sync settings**
   - Review what's configured to sync
   - Try manual sync
   - Check error logs

4. **Distributor status**
   - Check if distributor API is operational
   - Review any maintenance notices
   - Try again during business hours

### Duplicate Products After Sync

**Symptoms:** Same products appear multiple times

**Solutions:**

1. **SKU matching**
   - Ensure SKUs are unique
   - Check if products existed before sync
   - Use SKU matching instead of title

2. **Clean up duplicates**
   - Identify duplicate products
   - Delete extras (keep one)
   - Re-sync with correct settings

3. **Prevent future duplicates**
   - Configure proper matching fields
   - Use distributor SKUs
   - Don't mix manual and synced products

---

## Performance Issues

### Store Loading Slowly

**Symptoms:** Pages take long time to load

**Solutions:**

| Issue | Solution |
|-------|----------|
| **Large images** | Compress and resize images |
| **Too many products** | Paginate or filter collections |
| **Complex theme** | Simplify customizations |
| **Many apps/scripts** | Remove unused integrations |

**Optimization steps:**

1. Run speed test (Google PageSpeed)
2. Identify largest resources
3. Compress images under 500KB
4. Limit products per page to 24
5. Remove unused code

### Admin Panel Timing Out

**Symptoms:** Admin operations fail or take too long

**Solutions:**

1. **Large operations**
   - Break bulk operations into smaller batches
   - Import fewer products at once
   - Export in date ranges

2. **Browser issues**
   - Clear cache
   - Use fewer browser tabs
   - Close other applications

3. **Network issues**
   - Check connection stability
   - Try wired instead of WiFi
   - Avoid VPN if possible

---

## Error Messages

### Common Error Codes

| Error | Meaning | Solution |
|-------|---------|----------|
| **404** | Page not found | Check URL, verify page exists. If you changed a URL, add a redirect |
| **419** | Page session expired | Refresh the page and resubmit the form |
| **500** | Server error | Refresh, contact support if persists |
| **503** | Service unavailable | Wait and retry |
| **Gateway timeout** | Request took too long | Retry, simplify request |
| **Rate limited** | Too many requests | The API allows 60 requests per minute. Wait a minute and retry |

### "Something Went Wrong"

**Symptoms:** Generic error message

**Solutions:**

1. **Try again**
   - Wait a few seconds
   - Retry the operation
   - Often temporary

2. **Clear cache**
   - Clear browser cache
   - Try incognito mode
   - Try different browser

3. **Note details**
   - When did it occur?
   - What were you doing?
   - Is it reproducible?

4. **Contact support**
   - Provide error details
   - Include screenshots
   - Describe steps to reproduce

### "Session Expired"

**Symptoms:** Logged out unexpectedly

**Solutions:**

1. **Log back in**
   - Normal after about two hours of inactivity
   - Re-enter credentials

2. **Browser settings**
   - Ensure cookies are enabled
   - Don't use "never remember" settings
   - Disable aggressive privacy extensions

3. **Frequent expiration**
   - Check for conflicting sessions
   - Verify 2FA time sync
   - Contact support if persists

---

## Getting More Help

### Before Contacting Support

Gather this information:

- **Account email**
- **Store URL**
- **Error messages** (exact text or screenshot)
- **Steps to reproduce**
- **When it started**
- **What you've already tried**

### Useful Information to Include

| Type | Details |
|------|---------|
| **Browser** | Chrome, Firefox, Safari, Edge + version |
| **Device** | Desktop, laptop, tablet, phone |
| **Operating system** | Windows, Mac, iOS, Android |
| **Screenshots** | Error messages, unexpected behavior |
| **Timeline** | When did issue start |

### Contact Options

See [Contact Us](/support/contact) for all support channels and response times.

---

## Related Documentation

- [FAQ](/support/faq) - Frequently asked questions
- [Contact Us](/support/contact) - Get support
- [Getting Started](/getting-started) - Setup guide

Source: https://docs.firearmcart.com/support/troubleshooting/index.mdx