How to Use Debug Flags

Quagga2 includes several debug flags that enable diagnostic console output to help troubleshoot issues with barcode detection and decoding. This guide explains when and how to use them.

Overview

Debug flags control what information Quagga2 logs to the browser console. By default, all debug output is suppressed to keep your console clean. Enable specific flags when you need to diagnose problems.

Important Note

Debug flags only work when ENV.development is true (development builds). Production builds strip out all debug code to minimize bundle size.

Available Debug Flags

Debug flags are organized into three categories:

  1. Console logging flags - Print diagnostic information to the console
  2. Visual canvas overlays - Draw debugging information on the canvas
  3. Performance analysis - Display frequency and pattern data

Console Logging Flags

inputStream.debug.showImageDetails

What it shows: Image loading and frame grabber operations

Console output example:

*** frame_grabber_browser: willReadFrequency=undefined canvas=<canvas>
Image Loader: Loaded 3 images from /path/to/image.jpg

When to use:

How to enable:

Quagga.init({
  inputStream: {
    // ... your input config
    debug: {
      showImageDetails: true
    }
  },
  // ... rest of config
});

decoder.debug.printReaderInfo

What it shows: Barcode reader registration and initialization

Console output example:

* ImageWrapper getCanvasAndContext
Registering reader: code_128_reader
Before registering reader: EANReader
Registered Readers: code_128, ean

When to use:

How to enable:

Quagga.init({
  decoder: {
    readers: ["code_128_reader", "ean_reader"],
    debug: {
      printReaderInfo: true
    }
  },
  // ... rest of config
});

locator.debug.showPatchSize

What it shows: Patch dimensions during barcode localization

Console output example:

Patch-Size: 320x240

When to use:

How to enable:

Quagga.init({
  locator: {
    patchSize: "medium",
    debug: {
      showPatchSize: true
    }
  },
  // ... rest of config
});

locator.debug.showImageDetails

What it shows: Canvas and image wrapper initialization for locator

Console output example:

* initCanvas getCanvasAndContext
* ImageWrapper getCanvasAndContext

When to use:

How to enable:

Quagga.init({
  locator: {
    // ... your locator config
    debug: {
      showImageDetails: true
    }
  },
  // ... rest of config
});

Visual Canvas Overlay Flags

These flags draw debugging information directly on the canvas, allowing you to visualize the barcode detection algorithm’s internal state.

Note: The scan area overlay (defined via inputStream.area) is not a debug flag. When locate: false, Quagga draws the scan area on the overlay canvas each processed frame. You can also draw it manually using Quagga.drawScannerArea(). See the Configuration Reference and API.

decoder.debug.drawBoundingBox

What it shows: Draws a box around the detected barcode location

When to use:

How to enable:

Quagga.init({
  decoder: {
    debug: {
      drawBoundingBox: true
    }
  },
  // ... rest of config
});

decoder.debug.drawScanline

What it shows: Draws the scanline path used for decoding

When to use:

How to enable:

Quagga.init({
  decoder: {
    debug: {
      drawScanline: true
    }
  },
  // ... rest of config
});

locator.debug.showCanvas

What it shows: Displays the locator’s internal canvas used for image processing

When to use:

How to enable:

Quagga.init({
  locator: {
    debug: {
      showCanvas: true
    }
  },
  // ... rest of config
});

locator.debug.showPatches

What it shows: Draws all patches extracted during the localization phase

When to use:

How to enable:

Quagga.init({
  locator: {
    debug: {
      showPatches: true
    }
  },
  // ... rest of config
});

locator.debug.showFoundPatches

What it shows: Highlights patches where potential barcodes were found

When to use:

How to enable:

Quagga.init({
  locator: {
    debug: {
      showFoundPatches: true
    }
  },
  // ... rest of config
});

locator.debug.showSkeleton

What it shows: Displays the skeleton structure extracted from patches

When to use:

How to enable:

Quagga.init({
  locator: {
    debug: {
      showSkeleton: true
    }
  },
  // ... rest of config
});

locator.debug.showLabels

What it shows: Displays component labels during connected component analysis

When to use:

How to enable:

Quagga.init({
  locator: {
    debug: {
      showLabels: true
    }
  },
  // ... rest of config
});

locator.debug.showPatchLabels

What it shows: Shows labels assigned to individual patches

When to use:

How to enable:

Quagga.init({
  locator: {
    debug: {
      showPatchLabels: true
    }
  },
  // ... rest of config
});

locator.debug.showRemainingPatchLabels

What it shows: Displays labels for patches remaining after filtering

When to use:

How to enable:

Quagga.init({
  locator: {
    debug: {
      showRemainingPatchLabels: true
    }
  },
  // ... rest of config
});

locator.debug.boxFromPatches.showTransformed

What it shows: Shows transformed patch coordinates during box calculation

When to use:

How to enable:

Quagga.init({
  locator: {
    debug: {
      boxFromPatches: {
        showTransformed: true
      }
    }
  },
  // ... rest of config
});

locator.debug.boxFromPatches.showTransformedBox

What it shows: Displays the bounding box after transformation

When to use:

How to enable:

Quagga.init({
  locator: {
    debug: {
      boxFromPatches: {
        showTransformedBox: true
      }
    }
  },
  // ... rest of config
});

locator.debug.boxFromPatches.showBB

What it shows: Displays the final bounding box around detected barcode region

When to use:

How to enable:

Quagga.init({
  locator: {
    debug: {
      boxFromPatches: {
        showBB: true
      }
    }
  },
  // ... rest of config
});

Performance Analysis Flags

decoder.debug.showFrequency

What it shows: Displays frequency data from the barcode scanline

When to use:

How to enable:

Quagga.init({
  decoder: {
    debug: {
      showFrequency: true
    }
  },
  // ... rest of config
});

decoder.debug.showPattern

What it shows: Displays the pattern data extracted from the barcode

When to use:

How to enable:

Quagga.init({
  decoder: {
    debug: {
      showPattern: true
    }
  },
  // ... rest of config
});

Common Debugging Scenarios

“No barcodes detected”

Enable console logging first, then add visual overlays if needed:

Quagga.init({
  inputStream: {
    target: document.querySelector('#scanner'),
    debug: {
      showImageDetails: true
    }
  },
  decoder: {
    readers: ["code_128_reader"],
    debug: {
      printReaderInfo: true,
      drawBoundingBox: true,  // Visual: see if barcode is located
      drawScanline: true       // Visual: see scan path
    }
  },
  locator: {
    debug: {
      showPatchSize: true,
      showImageDetails: true,
      showFoundPatches: true   // Visual: see candidate patches
    }
  }
}, function(err) {
  if (err) {
    console.error("Init error:", err);
    return;
  }
  console.log("Starting Quagga...");
  Quagga.start();
});

Check console for:

Check canvas overlay for:

“Camera not working”

Enable input stream debugging:

Quagga.init({
  inputStream: {
    type: "LiveStream",
    debug: {
      showImageDetails: true  // Shows camera/canvas setup
    }
  },
  // ... rest of config
});

“Wrong barcode type detected”

Enable reader info to verify configuration:

Quagga.init({
  decoder: {
    readers: [
      "code_128_reader",  // Did you enable the right readers?
      "ean_reader"
    ],
    debug: {
      printReaderInfo: true  // Shows which readers are active
    }
  },
  // ... rest of config
});

“Deep-dive localization debugging”

For advanced debugging of the localization algorithm, enable all visual overlays:

Quagga.init({
  locator: {
    debug: {
      showCanvas: true,
      showPatches: true,
      showFoundPatches: true,
      showSkeleton: true,
      showLabels: true,
      showPatchLabels: true,
      showRemainingPatchLabels: true,
      boxFromPatches: {
        showTransformed: true,
        showTransformedBox: true,
        showBB: true
      }
    }
  }
}, function(err) {
  if (err) {
    console.error(err);
    return;
  }
  Quagga.start();
});

This will display every step of the localization process visually on the canvas. Use this to:

Warning: Enabling all visual overlays may impact performance and make the canvas cluttered. Enable only what you need.

Performance Impact

Debug flags have varying performance impacts:

Console logging flags (minimal impact):

Visual canvas overlays (moderate to high impact):

Performance analysis flags (high impact):

Recommendation: Enable only the flags you need. Disable all visual overlays for production.

Disabling Debug Output

To turn off all debug output, either:

Option 1: Remove debug properties entirely

Quagga.init({
  inputStream: {
    // debug property removed
  },
  // ...
});

Option 2: Set flags to false

Quagga.init({
  inputStream: {
    debug: {
      showImageDetails: false
    }
  },
  decoder: {
    debug: {
      printReaderInfo: false,
      drawBoundingBox: false,
      drawScanline: false,
      showFrequency: false,
      showPattern: false
    }
  },
  locator: {
    debug: {
      showCanvas: false,
      showPatches: false,
      showFoundPatches: false,
      showSkeleton: false,
      showLabels: false,
      showPatchLabels: false,
      showRemainingPatchLabels: false,
      showPatchSize: false,
      showImageDetails: false,
      boxFromPatches: {
        showTransformed: false,
        showTransformedBox: false,
        showBB: false
      }
    }
  }
});

Using in Node.js

Debug flags work in Node.js too! Output goes to console.log:

const Quagga = require('@ericblade/quagga2').default;

Quagga.decodeSingle({
  src: './barcode.jpg',
  decoder: {
    readers: ['code_128_reader'],
    debug: {
      printReaderInfo: true  // Shows reader registration
    }
  }
}, (result) => {
  // Check console for debug output
  if (result) {
    console.log('Decoded:', result.codeResult.code);
  }
});

Development vs Production

Development builds (dist/quagga.js or when using webpack dev server):

Production builds (dist/quagga.min.js):

To enable debug output in production:

  1. Use the development build (quagga.js instead of quagga.min.js)
  2. Set ENV.development = true before importing Quagga

Summary

Quagga2 provides 19 debug flags organized into three categories:

Console logging (4 flags) - Minimal performance impact:

Visual canvas overlays (13 flags) - Moderate to high performance impact:

Performance analysis (2 flags) - High impact:

Debugging strategy: Start with console logging flags, then add visual overlays as needed. Disable all flags in production.

Changelog

v1.8.4+ (November 2025): Debug flags introduced to replace always-on console spam

Prior versions logged debug information unconditionally, making it difficult to debug application code. The new flag system provides fine-grained control over diagnostic output.

Questions? Ask in Gitter Chat or open an issue.