Here are solutions to the most common issues merchants encounter with UserLoop Contests.

## Contest page shows "not found" (404)

**Cause:** The contest is not in Active status.

**Fix:**
1. Open the contest in your Shopify admin.
2. Check the status badge — it should say **Active**.
3. If it says Draft, click **Activate** to make it live.
4. If it says Ended or Archived, the page is intentionally unavailable.

Also check that you're using the correct URL slug. The URL format is:
```
https://yourstore.com/apps/contest/your-slug
```

## Popup is not showing on my storefront

**Possible causes and fixes:**

1. **The popup isn't enabled in your theme.**
   - Go to **Online Store > Themes > Customize**.
   - Check **App embeds** — make sure Contest Popup is toggled on.
   - Make sure a contest is selected in the popup settings.

2. **Frequency settings are blocking it.**
   - If set to "Once per visitor" and you've already seen it, it won't show again.
   - Try opening the page in an incognito/private browser window.
   - Or temporarily change the frequency to "Always" for testing.

3. **"Remember when dismissed" is on.**
   - If you previously closed the popup, it remembers. Clear your browser's local storage or use an incognito window.

4. **Page targeting is restricting where it shows.**
   - Check the page targeting settings. If "Show on all pages" is off, make sure the specific page type you're visiting is checked.

5. **The contest isn't active.**
   - Only active contests appear in the popup. Check the contest status.

## Entries are not appearing

**Possible causes:**

1. **Rate limiting.**
   - The app rate-limits entries by IP address to prevent spam. If you're testing repeatedly from the same IP, you may hit the limit.
   - Wait a few minutes and try again, or test from a different device/network.

2. **Contest isn't active.**
   - Entries are only accepted for active contests. Check the status.

3. **Email already entered.**
   - If the same email has already entered and the entries-per-customer limit is reached, no new entry is created. The customer sees a message that they've already entered.

## Customer sees "You've already entered"

**Cause:** The customer's email has already been used to enter the contest, and they've reached the maximum entries per customer.

**This is expected behavior.** Each email address can enter a set number of times (configured in Entry Settings). If you want to allow more entries, increase the "Entries per customer" setting on the contest's Setup tab.

## Theme blocks are not visible in the theme editor

**Fix:**

1. Go to **Online Store > Themes > Customize**.
2. For the **popup**: Look under **App embeds** (the paintbrush icon in the left sidebar). Toggle on Contest Popup.
3. For the **form block**: Navigate to the page where you want it, click **Add section** or **Add block**, and search for "Contest Form."

If you don't see the blocks at all:
- Make sure the app is installed and active.
- Try refreshing the theme editor.
- Check that you're editing the correct theme (your published/active theme).

## Contest colors aren't applying to theme blocks

**Cause:** The "Use contest colors" option might be turned off in the block settings.

**Fix:**
1. Open the theme editor.
2. Select the contest block (popup or form).
3. Check that **Use contest colors** is toggled on.
4. If it's off, the block uses its own color settings instead of the contest's Design tab colors.

## Images aren't uploading

**Possible causes:**

1. **File too large.** Images must be under 10 MB.
2. **Unsupported format.** Supported formats are: JPEG, PNG, GIF, WebP, and SVG.
3. **Permission issue.** The app needs the "Write files" permission. If you denied this during install, reinstall the app to re-grant permissions.

## Contest URL slug conflict

**Cause:** Another contest in your store already uses the same slug.

**Fix:** Each slug must be unique within your store. Edit the slug to something different. If you're duplicating a contest, the app automatically adds a timestamp to the slug to avoid conflicts.

## Need More Help?

If you're experiencing an issue not covered here, reach out to our support team. Include:
- Your store URL
- The contest name or slug
- A description of what you expected to happen vs. what actually happened
- Any error messages you saw