Troubleshooting

Common issues and solutions for the VerifyHuman Shopify app.

Widget Not Appearing

Symptom

The age gate, identity verification button, or human check badge does not appear on your storefront.

Solutions

1. Check the metafield is set.

   • Go to Settings > Diagnostics in the VerifyHuman dashboard.
   • If the metafield check shows "fail" or "warning", click Repair to set it automatically.
   • The metafield verifyhuman.app_url must point to the correct app URL (the origin, without /app).

2. Verify the Theme App Extension is enabled.

   • Go to Online Store > Themes > Customize.
   • Click App embeds in the sidebar.
   • Ensure the relevant VerifyHuman widget is toggled on.
   • Save the theme.

3. Check browser console for errors.

   • Open your storefront in an incognito window.
   • Open the browser developer console (F12 or Cmd+Opt+I).
   • Look for [VerifyHuman] messages.
   • If you see App URL metafield not set. Please reinstall the app., the metafield is missing. Use the Repair button in Diagnostics.

4. Confirm the feature is enabled in Settings.

   • Age Gate: agegateEnabled must be true.
   • Identity: identityEnabled must be true.
   • Human Check: humanEnabled must be true.
   • At least one sub-option must be enabled (e.g., for Human Check, at least one of signup/reviews/contact/all forms).

5. Check trigger mode and tags.

   • If the Age Gate trigger mode is set to Product Tag but you are not on a product page, the overlay will not appear.
   • If using Collection Tag, the overlay only appears on collection pages or product pages where the product belongs to a tagged collection.
   • Ensure tags are spelled exactly as configured (tags are case-insensitive).

Age Gate Not Showing on Specific Products

Symptom

The age gate overlay appears on some products but not others when using tag-based triggers.

Solutions

1. Verify the product has the correct tag.

   • In Shopify admin, go to the product and check its tags.
   • The default tag is age-restricted (case-insensitive).
   • Make sure there are no leading/trailing spaces in the tag.

2. Check trigger mode matches your intent.

   • all_pages: Shows on every page (no tags needed).
   • product_tag: Only on product pages where the product has the tag.
   • collection_tag: Only on collection pages or products in a tagged collection.
   • specific_pages: Only on pages matching the configured handles.

Identity Verification Block Not Visible

Symptom

The "Verify My Identity" button does not appear on the product page or section where you added it.

Solutions

1. Identity Verification is an App Block, not an App Embed.

   • It will NOT appear in the "App embeds" list.
   • You must add it manually: go to the specific page in Theme Editor, click + Add block in a section, and select Identity Verification under Apps.

2. Ensure the section supports app blocks.

   • Not all theme sections support app blocks. Try adding it to the main product section or a custom section.

Checkout Guard Not Blocking Checkout

Symptom

Products tagged with vh_requires_idv can be checked out without identity verification.

Solutions

1. Confirm the Checkout ID embed is enabled.

   • In Theme Editor, go to App embeds and toggle on VerifyHuman - Checkout ID.

2. Check the product tag.

   • The default tag is vh_requires_idv (case-insensitive).
   • Alternatively, set the product metafield verifyhuman.requires_idv to true.

3. Check the "All Checkouts" setting.

   • If you want every checkout to require verification regardless of tags, enable Require for All Checkouts.

4. Verify on the cart page.

   • The checkout guard activates on the cart page template. If your theme uses a drawer cart or AJAX cart without navigating to /cart, the guard may not activate. In that case, use the Cart Checkout Validation function extension for server-side enforcement.

Human Check Not Detecting Forms

Symptom

The human verification prompt does not appear when submitting forms.

Solutions

1. Enable the correct form type.

   • In the theme editor Human Check settings, ensure the relevant checkbox is enabled (Signup, Reviews, Contact, or All Forms).

2. Check default form selectors.

   • Signup: #create_customer, form[action*="/account"], .customer-form, [data-customer-form]
   • Reviews: .product-review-form, #review-form, .spr-form, .stamped-form, .jdgm-form, [data-review-form]
   • Contact: #contact-form, .contact-form, form[action*="/contact"], [data-contact-form]

3. Use custom selectors for non-standard themes.

   • If your theme uses different form IDs or classes, enter the correct CSS selectors in the Advanced: Custom Form Selectors section of the Human Check settings.

4. Enable debug mode.

   • Toggle Debug Mode on in the Human Check settings.
   • Open browser console and look for [VerifyHuman] logs showing which forms were found.

API Key Errors

Symptom: "VerifyHuman API key not configured"

• Go to Settings > API Configuration and enter your API key.
• Keys start with vhk_live_ (production) or vhk_test_ (testing).
• After entering the key, click Save Changes.

Symptom: "Verification service unavailable"

• The VerifyHuman API could not be reached. This may be a temporary outage.
• Check your API key is valid at app.verifyhuman.io.
• Verify you have sufficient usage quota remaining.

Symptom: "Server configuration error"

• This typically occurs when test mode is enabled but the test API key environment variable is missing.
• Contact your developer or hosting provider to check server environment variables.

Metafield Mismatch Warning

Symptom

Diagnostics shows: Metafield is set to "X" but expected "Y".

Solution

• Click the Repair button in the Diagnostics card.
• This updates the verifyhuman.app_url metafield to match the current app URL.
• The metafield should contain the origin URL only (e.g., https://your-app.example.com), not a path like /app.

Verification Fails with No Error Message

Possible Causes

1. Missing selfie image. The camera may not have been granted permission. Ensure the browser has camera access.
2. Missing date of birth. For age verification with selfie, a date of birth is required alongside the selfie.
3. Image too large or corrupted. Try with a well-lit selfie and ensure the camera is not blocked.
4. API timeout. Identity verification may time out after 60 seconds. The API call for age verification times out after 30 seconds.

Check Logs

• Go to the Logs page in the VerifyHuman dashboard.
• Filter by severity error to find specific error messages.
• Look for verification_failed or api_error event types.

Rate Limiting

Symptom

Receiving "Too many requests. Please try again later."

Cause

The app enforces a rate limit of 30 API requests per shop per 60-second window.

Solution

• Wait 60 seconds and try again.
• If you are running automated tests, reduce the request frequency.

Express Checkout Buttons Still Visible

Symptom

Shop Pay, Apple Pay, and Google Pay buttons are still visible even when identity verification is required.

Solution

1. In the Checkout ID settings, ensure Hide Express Checkout Buttons is toggled on.
2. This setting hides accelerated checkout buttons until the customer has been verified.
3. If the buttons still appear, check that the checkout guard is loading by looking for identity-checkout.js in the Network tab of browser dev tools.

Widget Loads But Shows Console Warning

Common Warnings

Still Need Help?

1. Run the full Diagnostics check in Settings.
2. Check the Logs page for error details.
3. Open browser dev tools and look for [VerifyHuman] console messages.
4. Contact support with your shop domain and the specific error messages you see.