Skip to content

Troubleshooting

Find your symptom, apply the fix, and check the result.

Most failures throw a QRCodeError with a code. Some problems, such as a missing center image, produce output without any error.

Symptom Go to
PAYLOAD_TOO_LARGE The payload does not fit
INVALID_PAYLOAD The payload is rejected
Scans as undefined or [object Object] The QR code scans as undefined
Unreadable after setting version or mask Output does not scan after setting matrix options
No center image, no error The center image is missing
RENDER_FAILED with a SecurityError The canvas is tainted
image.decode() rejects The center image fails to load
Clicking download does nothing A download does nothing
Terminal output is huge or wraps Terminal text is too large
Terminal output doesn’t scan A terminal QR code does not scan
ERR_REQUIRE_ESM ERR_REQUIRE_ESM in CommonJS
qrc prints Error: CLI commands fail
Styled code doesn’t scan The QR code does not scan
  • Check which QRCodeSDK packages and versions you have installed: npm ls @qrcodesdk/core or pnpm why @qrcodesdk/core.
  • Read error.code from the thrown error. The errors reference lists every code, when it is thrown, and its details.

Log the code, not the message or the whole error:

try {
// Render the QR code.
} catch (error) {
if (error instanceof Error && error.name === 'QRCodeError') {
console.error('QR code error:', (error as Error & {code: string}).code);
}
throw error;
}

details can contain user input. For example, INVALID_PAYLOAD puts the rejected payload in details.payload. Only log a details key after you check that it holds nothing sensitive.

React, Vue, Svelte, and Angular components report errors through the framework. See Check errors from framework packages.

Error: PAYLOAD_TOO_LARGE

Cause: The payload is larger than every version from 1 to 40 can hold, or larger than the version you pinned. Version 40 holds at most 2,953 bytes at error correction level L, and 1,273 bytes at level H.

Fix: Try these in order:

  1. Remove a pinned version, so the builder can choose a larger one.
  2. Shorten the payload. For URLs, drop tracking parameters or use a shorter path.
  3. Lower the error correction level, unless a center image covers modules.
  4. Enable mixed-mode segmentation for text that mixes digits, uppercase letters, and other characters.

Even when a large payload fits, its modules are small and harder to scan. Prefer short payloads.

Error: INVALID_PAYLOAD

Cause Fix
A concrete mode, such as 'numeric', doesn’t accept the whole payload Remove mode, or use 'auto'
A numeric payload is negative, fractional, or above Number.MAX_SAFE_INTEGER Pass it as a string. Do the same for identifiers with leading zeroes
A custom segmenter returns segments that don’t join to the original payload Fix the segmenter
mode: 'kanji' gets ASCII, half-width katakana, emoji, or another character outside Shift JIS Use auto mode with automaticSegmenter and kanji, which puts those characters in other segments
mode from JavaScript or JSON is not 'auto', 'numeric', 'alphanumeric', 'octet', or 'kanji' Use one of those values. details.mode shows the rejected value
A payload helper such as wifiPayload() rejects a field Fix the field named in details.field. Text fields, including email and SMS body, can’t contain line breaks

Payload helpers throw when you call them, not when you render.

Symptom: The code decodes to undefined, null, true, or [object Object]. No error is thrown.

Cause: The builder received something that isn’t a payload. TypeScript requires a string or number, but the builder doesn’t check the type at runtime. It converts any value with String() and encodes that text. Calling qrcode().matrix() from JavaScript with no payload encodes the text undefined. See Payload types are not validated at runtime.

Fix:

  1. Render the QR code only once the payload exists. For data that loads asynchronously, show a placeholder until the request completes.
  2. Check values from JavaScript, JSON, or other untyped sources with the isQRCodePayload() guard. A truthiness check such as if (payload) would also drop 0 and the empty string.
  3. Scan the result and compare the decoded text with what you expect.

In a framework component, wrap the QR code in a conditional that uses the guard. Import isQRCodePayload() into the component file. In Angular, also assign it to a class field so the template can call it.

// React
const url = data?.url;
return isQRCodePayload(url) ? <QRCodeSVG payload={url} /> : <p>Loading</p>;
<!-- Vue -->
<QRCodeSVG v-if="isQRCodePayload(url)" :payload="url" />
<p v-else>Loading</p>
<!-- Svelte -->
{#if isQRCodePayload(url)}
<QRCodeSVG payload={url} />
{:else}
<p>Loading</p>
{/if}
<!-- Angular -->
@let payload = url();
@if (isQRCodePayload(payload)) {
<qrcode-svg [payload]="payload" />
} @else {
<p>Loading</p>
}

Output does not scan after setting matrix options

Section titled “Output does not scan after setting matrix options”

Symptom: The code renders without an error, but scanners can’t read it.

Cause: The builder doesn’t validate mode, eci, errorCorrectionLevel, version, or mask at runtime. TypeScript rejects invalid values, but values from JavaScript, JSON, or a type assertion reach the encoder unchecked:

  • A mask of 9 or 2.5, or a version of 2.5 or 41, produces an unreadable matrix.
  • A version of 0 throws PAYLOAD_TOO_LARGE, even for a short payload.

Fix: Check the values, or remove the option to use automatic selection:

Option Valid values
version Integer from 1 to 40
mask Integer from 0 to 7
errorCorrectionLevel 'L', 'M', 'Q', or 'H'
eci Boolean

For a validation function, see Matrix options are not validated at runtime.

Symptom: The QR code renders without its center image. No error is thrown.

Cause: Usually, the center image comes from a different copy of the package than the renderer. Each renderer only recognizes values from its own copy of svgCenterImage(), canvasCenterImage(), or rasterCenterImage(). It silently ignores anything else.

Fix:

  1. Import the factory from the same package as the renderer or component. Framework users import svgCenterImage and canvasCenterImage from their framework package.
  2. List installed copies with npm ls @qrcodesdk/core @qrcodesdk/browser or pnpm why @qrcodesdk/core. If more than one version appears, install your direct @qrcodesdk/core or @qrcodesdk/browser dependency at the version your framework package uses. Then reinstall, so the package manager keeps a single copy.
  3. Pass the original value. Object spread, JSON.parse(JSON.stringify()), and structuredClone() create a new value that renderers don’t recognize.

Two copies also break instanceof QRCodeError, because each copy defines its own class.

Error: RENDER_FAILED from a PNG, WebP, GIF, or JPEG Image element renderer, with a SecurityError as cause. With the Canvas renderer, your later toBlob(), toDataURL(), or getImageData() call throws instead.

Cause: A cross-origin center image tainted the Canvas.

Fix: Serve the image from your own origin, or serve it with an Access-Control-Allow-Origin header and request it with CORS. Set crossOrigin before src:

const image = new Image();
image.crossOrigin = 'anonymous';
image.src = 'https://cdn.example.com/logo.png';
await image.decode();

Symptom: image.decode() rejects because the image cannot be fetched or decoded.

Fix: Render the QR code without the image, tell the user, and offer a retry. The status element announces changes to screen readers:

<div id="qrcode"></div>
<p id="logo-status" role="status"></p>
<button id="logo-retry" type="button" hidden>Retry loading the logo</button>
import {canvasCenterImage} from '@qrcodesdk/browser';
import {QRCodePNGImageRenderer} from '@qrcodesdk/browser/png';
import {qrcode} from '@qrcodesdk/core';
const builder = qrcode('https://qrcodesdk.dev').errorCorrection('H');
const accessibility = {alt: 'QR code: scan to open qrcodesdk.dev'};
const container = document.querySelector('#qrcode');
const status = document.querySelector('#logo-status');
const retry = document.querySelector<HTMLButtonElement>('#logo-retry');
async function loadImage(url: string): Promise<HTMLImageElement> {
const image = new Image();
image.src = url;
await image.decode();
return image;
}
async function renderWithLogo() {
if (!container || !status || !retry) return;
status.textContent = 'Loading the logo.';
retry.hidden = true;
try {
const logo = await loadImage('/logo.png');
const centerImage = canvasCenterImage(logo, {size: 0.3});
container.replaceChildren(builder.render(QRCodePNGImageRenderer({accessibility, centerImage})));
status.textContent = '';
} catch {
container.replaceChildren(builder.render(QRCodePNGImageRenderer({accessibility})));
status.textContent = 'The logo could not be loaded. The QR code works without it.';
retry.hidden = false;
}
}
retry?.addEventListener('click', () => void renderWithLogo());
void renderWithLogo();

The same pattern works in framework components:

  • Keep a loading, ready, or failed state.
  • Render the QR code without centerImage until the image is ready.
  • Show the status next to the QR code.

Cause: download() and the browser download renderers click a temporary link with a download attribute. Browsers and embedding apps can block or ignore that click.

Fix: Check each of these:

  • No user action. Some browsers block downloads that don’t follow a click or key press. Call download() directly in the click handler, not after an await, a timer, or on page load. Some browsers also ask for permission before several downloads in a row.
  • Iframe sandbox. An iframe with a sandbox attribute needs allow-downloads in it. Embedded previews and some site builders omit it. Open the page in a top-level tab to confirm.
  • In-app browsers. Browsers inside some social and messaging apps on iOS and Android ignore download, or open the image instead of saving it. Also show the code as an Image element, so users can save it with a long press. Or offer to open the page in the system browser.
  • Rendering failed. download() throws QRCodeError like any render, for example RENDER_FAILED for a tainted Canvas. Wrap the call in try/catch and check the console.

Cause: QRCodeTextRenderer uses the same defaults as the graphical renderers: moduleSize: 5 and quietZone: 4. A version 1 code then prints (21 + 2 × 4) × 5 = 145 columns.

Fix: Use one character cell per module and a smaller quiet zone, as the CLI does:

import {QRCodeTextRenderer, qrcode} from '@qrcodesdk/core';
const text = qrcode('https://qrcodesdk.dev').render(
QRCodeTextRenderer({style: {moduleSize: 1, quietZone: 2}}),
);

A version 1 code is then 25 columns wide and 13 lines high in the compact layout. If it still wraps, shorten the payload or widen the terminal.

Cause: Without ANSI colors, dark modules print as █ in the terminal’s text color, and light modules as spaces on the terminal’s background. On a dark theme, that gives an inverted code, which many scanners reject.

Fix:

  • In code: pass ansi: true to QRCodeTextRenderer. Dark modules become black and light modules white on every theme. If the font shows gaps between block glyphs, use ansi: {mode: 'background'}.
  • With the CLI: keep ANSI enabled. qrc turns it off when standard output is not a terminal or NO_COLOR is set. Pass --ansi blocks or --ansi background to force it on.
  • Either way: keep the quiet zone. With quietZone: 0, the terminal background touches the code.

See the terminal text renderer reference for the output of each layout and ANSI mode.

Cause: QRCodeSDK packages are ES modules only. Before Node.js 22.12, require() of an ES module throws ERR_REQUIRE_ESM.

Fix: Pick one:

  1. Upgrade to Node.js 22.12 or newer, where require() loads ES modules.
  2. Load the package with await import('@qrcodesdk/core') inside an async function.
  3. Convert the file to an ES module, for example by renaming it to .mjs or setting "type": "module" in package.json.

With module: 'commonjs', TypeScript compiles import() to require(). Set module to node16 or nodenext to keep the dynamic import. See Module format.

On any failure, qrc prints Error: <message> to standard error and exits with status 1.

Message or symptom Fix
Unknown option for a payload that starts with - End the command with -- "-42" after all options, or pass --payload "-42"
Expected at most one payload argument Quote a payload that contains spaces, and move every option in front of --
Missing QR payload in a pipeline or CI job Pass the payload as an argument; qrc does not read standard input
ENOENT when writing a file Create the parent directory first, for example with mkdir -p
Unable to infer output format from --output Use a .svg, .png, .webp, .gif, .jpg, or .jpeg path, or pass --format
--quality is only supported with jpeg output Remove --quality and --matte, or write JPEG
--layout cannot be combined with --ansi background Remove --layout; background mode has a fixed layout
A tiny PNG, WebP, GIF, or JPEG file Pass --module-size 8 --quiet-zone 4; the CLI defaults to 1 and 2
QRCode: Payload too large See The payload does not fit

See the CLI automation contract for exit statuses and file behavior.

Valid options can still produce a code that scanners can’t read. Try these:

  • Restore the four-module quiet zone.
  • Increase contrast and module size.
  • Make the center image smaller.
  • Simplify shapes.

See Scan reliability.

If none of these fixes apply, search the GitHub issues. Open a new issue with the error code, package versions, and a minimal reproduction.

Use a made-up payload that shows the same error. details can contain your original payload, so remove passwords, tokens, and personal data before you post it.

Support QRCodeSDK

If you find QRCodeSDK useful, please consider sponsoring the project!