Troubleshooting

Widget does not appear

Checklist:

• Confirm the CDN import runs with type="module".
• Confirm <docuworm-chat> is present in DOM.
• Check browser console for module load errors.

<script type="module">
  import "https://cdn.docuworm.ai/docuworm.js";
</script>

Access token is rejected

Typical causes:

• Token value is invalid or rotated.
• Current page origin is not in token allowed URLs.
• Localhost port mismatch.

Fix:

1. Regenerate token only if needed.
2. Re-check allowed URLs in dashboard API Keys.
3. Add exact local origin (for example http://localhost:5173).

Thread wait times out

waitForThreadId() can time out if initialization cannot complete.

Common causes:

• Invalid token/origin validation
• Script not loaded before helper call
• Widget element reference is null
• Waiting before a thread trigger (openWidget, upload*, or addSources)

Debug pattern:

const widget = document.querySelector("docuworm-chat");
console.log("widget exists", !!widget);

Upload succeeds but context is weak

Some MIME types upload but are not reliably extractable.

Guaranteed extraction support:

• application/pdf
• text/*
• image/jpeg, image/png, image/webp, image/gif

If using other types, convert to PDF or plain text before upload.

URL upload fails

For uploadFileFromUrl():

• URL must be browser-accessible.
• CORS must allow browser reads.
• Presigned URL must not be expired.

Helper calls do nothing

Control helpers are no-op when no widget element is found.

const widget = document.querySelector("docuworm-chat");
if (!widget) throw new Error("Docuworm element missing");

Expecting lifecycle event hooks

Current production API is helper/method based. Build thread sync and orchestration with helper calls (waitForThreadId, getThreadId, upload and source helpers).

Still blocked?

Capture and share:

• Browser console error output
• Exact page origin
• Token allowed URL list (redacted token value)
• Minimal embed snippet