Troubleshooting Guide

Likely cause

Your login credentials don't match any active account, or you may have signed up with a different email address (e.g. via Google OAuth vs. email/password).

Steps to resolve

1. 1.Confirm you are using the exact email address used during sign-up.
2. 2.If you signed up via Google, click "Continue with Google" instead of typing a password.
3. 3.Use "Forgot password?" on the login page to receive a reset link.
4. 4.Check your spam folder if the reset email does not arrive within two minutes.
5. 5.If the reset link says the account does not exist, the email address is not registered — create a new account.

Likely cause

Password reset is handled via a time-limited email link.

Steps to resolve

1. 1.Click "Forgot password?" on the login page.
2. 2.Enter the email address associated with your account and submit.
3. 3.Open the email from PassportBox and click the reset link — it expires in 15 minutes.
4. 4.Choose a new password (minimum 12 characters) and save.
5. 5.Log in with the new password.

Likely cause

Your authentication token has expired (sessions last 7 days) or your browser cleared cookies/local storage.

Steps to resolve

1. 1.Log in again. If the redirect loop continues, clear site cookies for passportbox.io.
2. 2.Disable any browser extensions that block cookies or storage (common with ad blockers and privacy extensions).
3. 3.Try an incognito/private window to rule out extension interference.
4. 4.If your organization enforces SSO, confirm your SSO session is still active in your identity provider.

Likely cause

PassportBox uses role-based access control. Viewer and Member roles cannot perform write operations; only Admin and Owner roles can manage billing, settings, and integrations.

Steps to resolve

1. 1.Go to Settings → Organization → Members to view your assigned role.
2. 2.Ask your organization Owner or Admin to update your role if broader access is needed.
3. 3.Note that billing and subscription management is restricted to the Owner role only.

Likely cause

Your subscription has ended — either it was cancelled, a payment failed and the grace period elapsed, or your trial expired.

Steps to resolve

1. 1.Navigate to /billing (you should still have access to this page).
2. 2.If your trial ended, select a plan and complete checkout.
3. 3.If you intended to keep the subscription, check that your payment method is valid and retry the payment.
4. 4.Existing passport data is preserved for 30 days after expiry; publish access is locked until a valid subscription is active.

Likely cause

Stripe attempted to charge the card on file and the charge was declined. The subscription enters a past_due state with a short grace period.

Steps to resolve

1. 1.Go to Billing → Manage Subscription.
2. 2.Click "Update payment method" and enter a valid card.
3. 3.Once saved, use "Retry payment" in the Stripe customer portal to immediately retry the outstanding invoice.
4. 4.The subscription status returns to active as soon as the invoice is paid.

Likely cause

Access is restricted during the expired or past_due states to prevent data modification on an unlicensed account.

Steps to resolve

1. 1.Resolve the subscription issue (see above).
2. 2.After payment confirms, refresh the page — access is restored immediately.
3. 3.If you just paid and access is still blocked after two minutes, log out and back in to refresh your session token.

Likely cause

Cancellation is handled through the Stripe customer portal. The button may be missing if you are not the account Owner.

Steps to resolve

1. 1.Confirm you are logged in as the account Owner (not Admin or Member).
2. 2.Go to Billing → Manage Subscription → Cancel plan.
3. 3.Cancellation takes effect at the end of the current billing period; you retain full access until then.

Likely cause

Each SKU must be unique within your organization. A product with this SKU already exists, possibly archived.

Steps to resolve

1. 1.Go to Products and search for the conflicting SKU.
2. 2.If the existing product is archived, either restore it or use a different SKU for the new product.
3. 3.If the existing product is active and correct, link your passport to it instead of creating a duplicate.

Likely cause

Products with one or more associated passports (in any status) cannot be deleted to preserve audit history.

Steps to resolve

1. 1.Go to Passports and filter by the product to find all linked passports.
2. 2.Archive all linked passports first.
3. 3.Return to Products and attempt deletion again.
4. 4.If you only want to hide the product, use Archive instead of Delete — archived products are excluded from all lists by default.

Likely cause

Your current plan has a maximum product count. You have reached that limit.

Steps to resolve

1. 1.Go to Billing and review your current plan limits.
2. 2.Upgrade to a higher tier to increase the product limit.
3. 3.Alternatively, archive products you are no longer actively using to free up slots.

Likely cause

The import may have completed with validation errors that caused all rows to be skipped, or the import job is still processing.

Steps to resolve

1. 1.Go to Import → Import History and check the status of the most recent job.
2. 2.If status is Failed, download the error report to see which rows were rejected and why.
3. 3.If status is Processing, wait up to two minutes and refresh.
4. 4.If status is Completed but shows 0 imported, all rows were skipped — review the error report for field-level validation failures (missing SKU, invalid category, etc.).

Likely cause

Publishing requires all required fields to be present. The compliance validator checks fields before allowing publication.

Steps to resolve

1. 1.Open the passport and scroll to the Compliance Score section.
2. 2.Fields marked with a red indicator are required for publication — complete all of them.
3. 3.At minimum: passport name, linked product, at least one material entry, and a supplier must be set.
4. 4.Save the draft after filling in required fields, then retry publishing.

Likely cause

GS1 Digital Links are only generated after a passport is published. Draft passports do not have a resolvable link.

Steps to resolve

1. 1.Confirm the passport status is PUBLISHED (green badge).
2. 2.Copy the GS1 Digital Link from the passport detail page and paste it into a browser.
3. 3.If it shows a 404, wait 30 seconds and retry — DNS propagation or CDN caching may cause a brief delay after first publish.
4. 4.If it still fails after one minute, check that your organization's GTIN is set correctly in Settings → Organization.

Likely cause

The passport may be archived, the QR code may have been generated before the passport was published, or the label encodes an outdated URL.

Steps to resolve

1. 1.Confirm the passport is in PUBLISHED status.
2. 2.Check that you are scanning the QR code generated after the passport was published, not a preview or draft label.
3. 3.Regenerate the label from the Labels page and scan the new code.

Likely cause

A background validation job may have rejected the publish request due to a field constraint that was not surfaced in the UI.

Steps to resolve

1. 1.Reload the page — if the status changed, the publish succeeded but the UI did not update.
2. 2.Open the passport edit form and save it again to trigger re-validation.
3. 3.Check that all required fields (name, product, materials, supplier) are populated.

Likely cause

Labels can only be generated for passports in PUBLISHED status. Draft and archived passports do not have a resolvable GS1 link to encode.

Steps to resolve

1. 1.Go to Passports and confirm the target passport shows status PUBLISHED.
2. 2.If the passport is still in DRAFT, complete all required fields and publish it first.
3. 3.Return to Labels, select the now-published passport, and generate the label.

Likely cause

The QR code may be too small, printed at too low a resolution, or obscured by glare or surface texture.

Steps to resolve

1. 1.Download the PDF version of the label (not the PNG) for the highest-fidelity output.
2. 2.Ensure the QR code is printed at a minimum size of 20mm × 20mm with a quiet zone (white border) of at least 4mm on all sides.
3. 3.Avoid glossy or reflective surfaces — matte finishes scan more reliably.
4. 4.Test with multiple phone models and camera apps; some older devices struggle with high-density QR codes.

Likely cause

The PDF generation job may have failed, or your browser is blocking the download.

Steps to resolve

1. 1.Disable any popup blockers or download managers for passportbox.io.
2. 2.Try a different browser.
3. 3.If the download button shows a spinner indefinitely, reload the page and regenerate the label before downloading.

Likely cause

The PNG export is rasterized at 300 DPI, which is sufficient for most labels but may appear soft when enlarged significantly.

Steps to resolve

1. 1.Use the PDF download for vector-quality output that scales to any print size without quality loss.
2. 2.If your print vendor requires a specific DPI or file format beyond what PassportBox exports, use the PDF with your design tool (Illustrator, InDesign) to embed it at the required spec.

Likely cause

The file may have encoding issues, an unsupported delimiter, or may exceed the 10 MB file size limit.

Steps to resolve

1. 1.Ensure the file is UTF-8 encoded and uses a comma delimiter (not semicolons or tabs).
2. 2.Remove any byte-order mark (BOM) if exporting from Excel — save as CSV UTF-8 (without BOM).
3. 3.Confirm the file is under 10 MB. For larger catalogs, split into multiple files.
4. 4.Download the CSV template from the Import page and compare your column headers exactly — column names are case-sensitive.

Likely cause

The Shopify domain may not be configured in your organization settings, or the OAuth connection has expired.

Steps to resolve

1. 1.Go to Settings → Integrations → Shopify.
2. 2.Confirm your Shopify domain is set in the format yourstore.myshopify.com (not a custom domain).
3. 3.If the domain is correct but products are still missing, disconnect and reconnect the Shopify integration to refresh the OAuth token.
4. 4.After reconnecting, return to Import → Shopify and trigger a manual sync.

Likely cause

All rows failed validation. Common causes: duplicate SKUs, missing required columns, or values that don't match allowed enumerations (e.g. category names).

Steps to resolve

1. 1.Download the error report from Import → Import History for the failed job.
2. 2.The report lists each rejected row with a reason. Address each validation error.
3. 3.For category fields, use the exact values listed in the CSV template (case-sensitive).
4. 4.Re-upload the corrected file.

Likely cause

Analytics only records data when a published passport's GS1 Digital Link or public URL is accessed. If no scans have occurred, there will be no data.

Steps to resolve

1. 1.Confirm at least one passport is PUBLISHED and has been scanned or accessed via its public URL.
2. 2.Scan your own QR code with a phone to generate a test scan event — it may take up to 60 seconds to appear.
3. 3.Check that the date range filter includes today.

Likely cause

Duplicate scans from the same IP address within a short window may be deduplicated. Bot traffic and internal team scans are also filtered.

Steps to resolve

1. 1.Review the raw scan event table (Analytics → Scans → Event Log) to see all recorded events, including filtered ones.
2. 2.If you are testing by scanning repeatedly from the same device, wait at least 30 seconds between scans to avoid deduplication.
3. 3.Internal office IPs can be excluded from counts via Settings → Analytics → IP Exclusions.