ExpressConsent

Troubleshooting

Fix common issues with missing CDRs, incomplete evidence, rendering problems, or SDK errors.

First checks

  1. Confirm your handler awaits captureCDR() before page navigation.
  2. During integration, use devMode: true and open the dashboard link in the console diagnostic group. The link waits for rendering automatically.
  3. Confirm you are looking under Domains → your domain → CDRs in the dashboard.

SDK not loaded

  • Confirm the script tag is present.
  • Confirm your Content Security Policy allows sdk.expressconsent.com.
  • Test in a clean browser profile to rule out blockers and extensions.
  • If the form is in an iframe, load the script inside that iframe.

The script has to be in the same document as the form. It reads the page it is loaded into and nothing else.

CDR never appears

  • The page navigates before captureCDR() resolves.
  • The handler throws and exits early.
  • SPA routing unmounts the form immediately.

Use this pattern:

javascript
const form = document.getElementById("consentForm");

form?.addEventListener("submit", async (event) => {
  event.preventDefault();

  try {
    const { cdrId } = await window.ExpressConsent.captureCDR();
    console.log("Saved:", cdrId);
  } catch (error) {
    console.error("ExpressConsent capture failed:", error);
  }

  form.submit();
});

Dev Mode record is waiting or unavailable

  • The dashboard link says it is waiting or rendering. Keep the page open. The upload is stored before the visual record is rendered, and the Dev Mode link polls until it is ready.
  • There is a cdrId but no finished image after a minute. Include that ID when contacting support. Durable storage succeeded, but rendering did not finish normally.
  • There is no downloadUrl, or collected is false. That is expected. Dev Mode records are free and uncollected. Producer-organization members, including passthrough accounts, preview them through the dashboard instead.
  • Collect, API share, or token claim returns 409 CDR_DEV_MODE. That is permanent for this record, not a retryable processing error. Dashboard public viewer links and PDFs remain available and are visibly marked Dev Mode.

Highlighting issues

Tag each submit control with data-ec-submit. The control must still be on the page when captureCDR() runs.

If the submit control is inside an iframe, load the SDK inside the iframe. The parent page cannot inspect a cross-origin iframe.

A supporting document reads "Unavailable"

The dashboard shows a reason code beside the document. The ones you can act on:

  • unsupported_javascript_page: the destination paints its text with JavaScript. We read the first HTTP response and run no scripts, so serve the legal text from the server. A JS bot-challenge page lands here too.
  • unsafe_url: the link is not HTTPS, or its host does not resolve to a public address. Staging hosts and internal addresses are unreachable.
  • http_error: the destination answered with something outside the 200s, or redirected more than five times. A WAF 403 lands here.
  • too_large: over 2 MiB of HTML, or over 20 MiB of PDF.
  • unsupported_content_type: the response was neither HTML nor PDF.
  • timeout: the destination did not answer within ten seconds. A rate limit that holds the connection open lands here.

fetch_failed and invalid_content mean the retrieval broke down before anything could be stored, such as a DNS or connection failure, or a response that did not hold what its content type promised. Bot protection that drops datacenter IPs often shows up as fetch_failed. See Archive linked documents for the User-Agent to allowlist and the full requirements.

Ensuring your page renders well

  • Use standard HTML controls for checkboxes, radio buttons, and inputs.
  • Make checked states clearly visible.
  • Keep entered values in the form until capture finishes.
  • Use real HTML text for consent language, not an image.
  • Keep the complete disclosure visible when the form is submitted.

Common rendering problems

  • Cross-origin iframe content can appear blank. Put the consent form in the top-level page or load the SDK inside the iframe.
  • Animations, overlays, and loading spinners can cover consent elements. Start them after capture.
  • Content loaded late might not be present. Render consent language before submission.
  • Lazy-loaded consent assets might be missing. Load them normally.
  • Local assets are not reachable by the renderer. Use inlineAssets: true during local development, or test on a public staging site.

Responsive design

  • Show the full consent language at every viewport size.
  • Keep accordions or tabs containing consent language open when the form is submitted.

Fonts and styles

  • Allow remote fonts and stylesheets in your Content Security Policy.
  • Add CORS headers to font files served from another domain.
  • Use crossorigin="anonymous" on cross-domain stylesheet links.

Need help?

When contacting support, include:

  • Your organization ID (CID)
  • The failing page URL, with personal data removed from query parameters
  • Browser console errors
  • A sample cdrId, if available

Contact support.