Skip to content
demuddler

Troubleshooting

Fix loading errors, licence checks, schema rules and failed row delivery. Find the cause of file and display problems.

Start with the step that fails. For a message in the importer, read Import messages. For dates, numbers, encodings or memory, read Fix file problems.

The importer is blank or never becomes ready

Section titled “The importer is blank or never becomes ready”
Symptom Check Next action
You cannot see the importer Does the element have a height above zero? For the first test, set style="height: 640px".
The tag stays an unknown element Did the package load in the browser? Import @demuddler/importer in the client bundle. Look for module resolution errors.
The browser cannot resolve the package name Does a bare import run without a bundler? Use the bundler of your app or set up an import map. An npm install alone does not change how the browser resolves names.
The browser blocks the frame request Does frame-src permit https://runtime.demuddler.com? Add the source to the policy that the response sends. Read all CSP headers. See Parent Content Security Policy.
The browser refuses to embed the frame Does the page open from a file:// address? Serve the page over HTTPS, or over HTTP on a local host. A file:// page cannot embed the importer.
An error event says “The importer is not connected.” The frame did not connect within 20 seconds. Did the runtime document and its assets load? Before you try again, read the failed request and the CSP error.

If a request fails, record its URL path, status and error code. Do not copy request bodies, cookies or keys into logs or support messages.

A refused licence stops the importer: it opens no file and shows “This importer is not set up”. importer.licence.is_licensed is false. importer.licence.reason and the licence event name the cause:

Reason or condition Meaning Action
missing The page set no licence key. Set licenceKey before the importer starts.
not_embedded The frame is not directly embedded in an HTTPS page or a local HTTP page. Put the loader in the page itself, and use HTTPS.
invalid_licence_key The key has the wrong form or names no licence. Copy the public licence key from Account. A replaced key stops working on the next load.
domain_not_allowed The licence does not cover the parent hostname, or the hostname is on a site beyond the sites of your plan. Register the hostname, or change the plan. See Domain matching and Sites.
domain_blocked We blocked the parent hostname. See Blocked sites and accounts. A new key or a new account does not lift a block. The Terms of use give the rules.
licence_agreement_not_accepted The licence owner did not accept the agreement. Sign in to the owner’s account and accept the agreement.
refused The API refused the request for another reason, for example a malformed hostname. Report the status and the time.
invalid_answer The answer of the API failed the signature check. Something between the browser and the API changed it, or the clock of the device is wrong by more than 5 minutes. Set the clock of the device. Look at proxies and browser extensions that change requests. Then report the time.
unreachable The API did not answer, or it limited the requests. With a stored answer for the hostname, the importer keeps its plan and is_licensed is true, except when the API limited the requests of the browser address. Otherwise it opens no file. The frame checks again and takes the answer when the API answers. See The licence check. Make sure that the browser can reach https://demuddler.com/api. Look at network filters and browser extensions.
It works in production but not locally The local hostname is different. Register the local hostname that the page uses. See Local development.
A licence change has no effect An open frame keeps its plan. Load the importer again.
A Development badge shows The page is on a local host with a paid plan. This is correct. See Local development.

A new runtime URL does not fix a missing or refused key.

Set schema as an object property. An HTML attribute holds text, not a ImporterSchema. In React, use schema={schema}. In Vue, use .prop when you bind object settings. Frameworks shows both.

Use plain arrays, objects and primitive values. A schema cannot hold functions, Zod objects or DOM nodes. To use an existing definition, see Existing JSON Schema, Zod or OpenAPI definitions.

If a rule is unavailable, see When a rule cannot run. Do not remove a required business check only to make the warning go away.

Symptom Next action
Setting a property throws a TypeError Read the message. It names the setting and the first problem. Correct that value.
An error event says that a key is not a known setting Correct the spelling, or remove the key. The importer does not ignore unknown keys.
An error event says that a value can hold at most a number of items or characters Make the value smaller. See Limits and refused schemas.
The importer shows “The page gave the importer a schema that it cannot use.” Read the error event, correct the schema and set it again. The importer stays stopped until it receives a schema that passes.
An error event says that the importer sent an unreadable message Make sure that the runtime URL names a released version. Then report the runtime URL and the time.

A refused setting keeps its earlier value. Refused settings lists the checks for each setting.

The finish action downloads instead of calling my handler

Section titled “The finish action downloads instead of calling my handler”

For a custom element, set handoff = true and attach complete to the element itself. Events do not bubble to a parent container. In React, supply onComplete, which turns on handoff.

To remove the downloads, set noFile together with handoff. See Attributes and scalar properties.

Completion happens before my requests finish

Section titled “Completion happens before my requests finish”

Call detail.waitUntil(deliver(detail.result)) during the event. In React, return the promise from onComplete. Inside that promise, read all batches and wait for the final commit on your server.

The error This delivery has ended. Read batches inside waitUntil. means that your code read the result after the registered work finished. See Deliver rows.

Some rows are missing, repeated or have different values

Section titled “Some rows are missing, repeated or have different values”
  1. Compare the count that you received with the source count and your plan limit.
  2. Look at the choices in the Import step, and at the skipInvalid, skipDuplicates and skipExcluded options that your code sets.
  3. Use batch.rowNumbers to find source data rows. Do not use a batch index or a physical file line as the data row number.
  4. Look at the retry policy of your backend. A new call of batches() reads from the start. It does not continue after your last successful request.
  5. Look at the read settings of the source, the edits and the destination types. A number read can remove leading zeros. Use text for identifiers.

Filters and column widths change only the display. They do not select rows for export. If a value cannot convert, do not catch the error and commit an earlier partial result.

CSS from your page does not enter the frame. Use appearance and the part names. A custom stylesheet needs Starter or Pro. A font name alone does not load a font into the frame. See Styling.

When you change appearance, features or schema, assign a new object. See Object properties.

The importer does not keep the open file or its edits. A refresh starts again with no file. Ask people to finish an import before they leave the page.

Question Answer
Are spreadsheet formulas recalculated? No. The importer uses the results that the workbook stored. See Formula results can be out of date.
Can the importer find records that are already in my database? It can refuse values that your database already holds, through validation hooks. To update existing records, deliver every row and let your backend insert or update each row by its key.
Does a successful import prove that every row satisfies my business rules? No. It proves only that your registered handler finished its work. Your backend must check the rows again.
Does a file always open when it is below a certain size? No. Device memory, the number of columns and the length of values change the memory that a file needs. See Performance.
Can I hide the attribution mark or the Development badge? Starter and Pro remove the attribution mark. The Development badge shows only on a local host, and no features flag or message removes it. See Licensing.
Do my users need Demuddler accounts? No. The account and the licence belong to the product that embeds the importer.

Include these items:

  • The package version and the framework version
  • The browser and the operating system
  • The runtime URL
  • The step that fails, the result that you expected and the error text
  • A minimal invented sample
  • Where the problem occurs: on a local host, preview, production or all three

Do not send a customer file, a private key, a sign-in code, a cookie, or a network archive that contains credentials. Support gives the support contact and the support for each plan.