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 |
Before you start
Section titled “Before you start”- Check which QRCodeSDK packages and versions you have installed:
npm ls @qrcodesdk/coreorpnpm why @qrcodesdk/core. - Read
error.codefrom the thrown error. The errors reference lists every code, when it is thrown, and itsdetails.
Find the error code
Section titled “Find the error code”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.
The payload does not fit
Section titled “The payload does not fit”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:
- Remove a pinned
version, so the builder can choose a larger one. - Shorten the payload. For URLs, drop tracking parameters or use a shorter path.
- Lower the error correction level, unless a center image covers modules.
- 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.
The payload is rejected
Section titled “The payload is rejected”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.
The QR code scans as undefined
Section titled “The QR code scans as undefined”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:
- Render the QR code only once the payload exists. For data that loads asynchronously, show a placeholder until the request completes.
- Check values from JavaScript, JSON, or other untyped sources with the
isQRCodePayload()guard. A truthiness check such asif (payload)would also drop0and the empty string. - 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.
// Reactconst 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
maskof9or2.5, or aversionof2.5or41, produces an unreadable matrix. - A
versionof0throwsPAYLOAD_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.
The center image is missing
Section titled “The center image is missing”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:
- Import the factory from the same package as the renderer or component. Framework users import
svgCenterImageandcanvasCenterImagefrom their framework package. - List installed copies with
npm ls @qrcodesdk/core @qrcodesdk/browserorpnpm why @qrcodesdk/core. If more than one version appears, install your direct@qrcodesdk/coreor@qrcodesdk/browserdependency at the version your framework package uses. Then reinstall, so the package manager keeps a single copy. - Pass the original value. Object spread,
JSON.parse(JSON.stringify()), andstructuredClone()create a new value that renderers don’t recognize.
Two copies also break instanceof QRCodeError, because each copy defines its own class.
The canvas is tainted
Section titled “The canvas is tainted”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();The center image fails to load
Section titled “The center image fails to load”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
centerImageuntil the image is ready. - Show the status next to the QR code.
A download does nothing
Section titled “A download does nothing”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 anawait, a timer, or on page load. Some browsers also ask for permission before several downloads in a row. - Iframe sandbox. An iframe with a
sandboxattribute needsallow-downloadsin 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()throwsQRCodeErrorlike any render, for exampleRENDER_FAILEDfor a tainted Canvas. Wrap the call intry/catchand check the console.
Terminal text is too large
Section titled “Terminal text is too large”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.
A terminal QR code does not scan
Section titled “A terminal QR code does not scan”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: truetoQRCodeTextRenderer. Dark modules become black and light modules white on every theme. If the font shows gaps between block glyphs, useansi: {mode: 'background'}. - With the CLI: keep ANSI enabled.
qrcturns it off when standard output is not a terminal orNO_COLORis set. Pass--ansi blocksor--ansi backgroundto 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.
ERR_REQUIRE_ESM in CommonJS
Section titled “ERR_REQUIRE_ESM in CommonJS”Cause: QRCodeSDK packages are ES modules only. Before Node.js 22.12, require() of an ES module
throws ERR_REQUIRE_ESM.
Fix: Pick one:
- Upgrade to Node.js 22.12 or newer, where
require()loads ES modules. - Load the package with
await import('@qrcodesdk/core')inside anasyncfunction. - Convert the file to an ES module, for example by renaming it to
.mjsor setting"type": "module"inpackage.json.
With module: 'commonjs', TypeScript compiles import() to require(). Set module to node16
or nodenext to keep the dynamic import. See
Module format.
CLI commands fail
Section titled “CLI commands fail”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.
The QR code does not scan
Section titled “The QR code does not scan”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.
Next step
Section titled “Next step”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.
Related pages
Section titled “Related pages”Support QRCodeSDK
If you find QRCodeSDK useful, please consider sponsoring the project!