QR Code Value is larger than the max len. Did you return the

Error message

QR Code Value is larger than the max len. Did you return the image base64 text by mistake? See: https://github.com/wechaty/wechaty/issues/1889

What it means

guardQrCodeValue() enforces that QR code string values do not exceed MAX_LEN = 7089 characters, the capacity of a version-40 QR code. If the value passed to it is longer — almost always because someone returned an image (e.g. base64 PNG data) instead of the QR payload text — it throws with a pointer to issue #1889. This is a data-shape sanity guard on puppet callbacks.

Source

Thrown at src/pure-functions/guard-qr-code-value.ts:24

 *
 *   Licensed under the Apache License, Version 2.0 (the "License");
 *   you may not use this file except in compliance with the License.
 *   You may obtain a copy of the License at
 *
 *       http://www.apache.org/licenses/LICENSE-2.0
 *
 *   Unless required by applicable law or agreed to in writing, software
 *   distributed under the License is distributed on an "AS IS" BASIS,
 *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *   See the License for the specific language governing permissions and
 *   limitations under the License.
 *
 */
const MAX_LEN = 7089

export function guardQrCodeValue (value: string): string {
  if (value.length > MAX_LEN) {
    throw new Error('QR Code Value is larger than the max len. Did you return the image base64 text by mistake? See: https://github.com/wechaty/wechaty/issues/1889')
  }
  return value
}

View on GitHub (pinned to 5a0520ac7d)

Solutions

Fix the puppet implementation to return the QR payload text (the encoded string), not an image or its base64.
If you must show an image, generate the QR image from the short payload string on the client side (e.g. qrcode-terminal) rather than passing it through.
Check for accidental FileBox.toBase64() or buffer.toString('base64') calls in the puppet's QR code path.
Update the puppet service package — this bug was fixed in mainstream puppets after wechaty issue #1889.

Example fix

// before (puppet onScan)
onScan(qrcode) { emit('scan', Buffer.from(qrcode).toString('base64')) }
// after
onScan(qrcode) { emit('scan', qrcode) } // pass the raw QR payload string

Defensive patterns

Strategy: validation

Validate before calling

const MAX_QR_LEN = 7089
function isQrCodeValue(v) {
  return typeof v === 'string' && v.length <= MAX_QR_LEN
}
// before using a puppet-provided qrcode value
if (!isQrCodeValue(qrValue)) {
  console.warn('qrcode value looks like an image, not a QR payload')
}

Type guard

function isQrCodePayload(v: unknown): v is string {
  return typeof v === 'string' && v.length <= 7089
}

Try / catch

try {
  const qr = await bot.userSelf().qrcode()
} catch (e) {
  if (String(e.message).includes('QR Code Value is larger than the max len')) {
    console.error('Puppet returned image data instead of QR payload; fix or update the puppet')
  }
  throw e
}

Prevention

Keep puppet-service implementations updated (post-#1889 puppets return the payload text).
Never pass FileBox/base64 image output into QR-code fields.
Add a length check on QR values in custom puppet code before emitting them.

When it happens

Trigger: A puppet implementation's onLogin/onScan callback (or contactSelfQRCode path) returns base64 image data or an HTML data-URI as the qrcode value, and guardQrCodeValue (called from qrcode()/qrCode()) receives it.

Common situations: Custom or buggy puppet services returning screenshot/base64 images for the login QR; developers implementing their own puppet returning FileBox base64 text instead of the encoded QR content.

Related errors

AI-assisted analysis of wechaty/wechaty@5a0520ac7d (2026-09-01). Data as JSON: /api/errors/5c1d7852f1cc9d9a. Report an issue: GitHub.