Troubleshooting

Start with the browser Network and Console panels, then inspect the result returned by your backend. Keep the HumanPass request ID when asking for support.

Widget does not appear

Check that:

• the versioned widget script returns HTTP 200;
• customElements.get("humanpass-widget") returns a component;
• data-humanpass-sitekey is present and uses the correct environment;
• Content Security Policy allows the script, API connection, and blob workers;
• the selected mode is not Invisible, which intentionally has no persistent UI.

403 Not allowed

The browser origin or action is not allowed for the site.

1. Confirm the sitekey belongs to the intended site.
2. Add the exact hostname in the dashboard.
3. For wildcard policy, remember it matches exactly one subdomain label.
4. Confirm data-humanpass-action is listed in Allowed actions.
5. If the action list is empty, omit the attribute or use default.

Localhost fails

Use a test site and add localhost as an exact allowed domain in the dashboard. Keep the standard widget script and use the site’s test sitekey:

<script
  src="https://humanpass.valgix.com/widget/0.1.0/humanpass.min.js"
  defer
></script>

<humanpass-widget
  data-humanpass-sitekey="hp_site_test_REPLACE_ME"
></humanpass-widget>

Open the page from http://localhost or http://localhost:<port>. An IP alias such as 127.0.0.1 is a different hostname and must be configured separately if you use it.

Script is blocked despite HTTP 200

An outer proxy may be adding restrictive cross-origin headers or serving the wrong MIME type. The official widget response must remain usable cross-origin. Check Content-Type, Cross-Origin-Resource-Policy, Content Security Policy, and any CDN or reverse-proxy overrides.

timeout_or_duplicate

The response expired or has already been consumed. Reset the widget and obtain a fresh response. Do not retry the old response under a new idempotency key.

invalid_secret

Confirm that the backend secret:

• includes the complete hp_secret_... value without quotes or whitespace;
• belongs to the same site and environment as the sitekey;
• has not been revoked;
• is loaded in the running deployment, not only in a local .env file.

action_mismatch or hostname_mismatch

Compare the widget action, dashboard allowlist, backend expected action, browser hostname, allowed domains, and SDK expectedHostname. The hostname must not include a scheme, path, or port.

rate_limited

Respect the HTTP Retry-After header. Avoid immediate loops, duplicate programmatic solves, and creating a new HumanPass request on every render.

service_unavailable or transport errors

Fail closed and show a retry message. Check connectivity to humanpass.valgix.com, DNS, TLS, proxy policy, and service status. Do not bypass HumanPass automatically.

Contact support

Send sayhello@valgix.com:

• the approximate UTC time;
• request ID and stable error code;
• affected hostname and action;
• widget and SDK versions;
• browser/runtime versions.

Do not send secret keys or complete response tokens.