Aspose.BarCode FOSS
Python
Troubleshooting Aspose.BarCode FOSS for Python

Troubleshooting Aspose.BarCode FOSS for Python

This guide covers the most common errors and issues when generating barcodes with Aspose.BarCode FOSS for Python (pip install aspose-barcode-foss). Each section describes the error, its cause, and how to fix it.

Common Errors

InvalidInputError

InvalidInputError is raised when the data passed to the encoder does not conform to the symbology’s character set or length requirements.

Typical causes:

  • Passing alphabetic characters to a numeric-only symbology (EAN-13, EAN-8, UPC-A, UPC-E)
  • Providing a string whose length does not match the symbology’s fixed-length requirement (e.g. EAN-13 requires exactly 12 or 13 digits)
  • Including characters outside the symbology’s supported set (e.g. Code 39 base mode only supports uppercase letters, digits, and a few special characters)

Fix: Validate your input data before calling BarcodeService.generate(). Check the symbology profile’s capabilities and known_limitations properties for character set and length constraints.

from aspose_barcode_foss import BarcodeService

service = BarcodeService()

# EAN-13 requires exactly 12 or 13 digits
data = "590123412345"  # 12 digits — valid
barcode = service.generate("ean13", data)

EncodingError

EncodingError is raised when the encoder encounters an internal failure after input validation passes. This is less common than InvalidInputError.

Typical causes:

  • Data that passes initial validation but fails during segment encoding (e.g. QR Code data that exceeds capacity for the chosen error correction level)
  • Conflicting encode options (e.g. requesting Code128EncodeMode.CODE_A with data that contains lowercase characters)

Fix: Review the encode options passed to generate(). For Code 128, use Code128EncodeMode.AUTO to let the encoder select the optimal subset. For QR Code, try a lower QrErrorCorrectionLevel or reduce the data length.

from aspose_barcode_foss import BarcodeService, Code128Options, Code128EncodeMode

service = BarcodeService()
options = Code128Options(encode_mode=Code128EncodeMode.AUTO)
barcode = service.generate("code128", "Hello123", encode=options)

SymbologyNotFoundError

SymbologyNotFoundError is raised when the symbology name passed to BarcodeService.generate() is not registered in the SymbologyRegistry.

Typical causes:

  • Misspelled symbology name (e.g. "code_128" instead of "code128")
  • Using a symbology that is not supported by the library (the library supports Code 128, Code 39, EAN-13, EAN-8, QR Code, UPC-A, and UPC-E only)

Fix: Use one of the seven supported symbology identifiers: "code128", "code39", "ean13", "ean8", "qrcode", "upca", "upce". Names are case-insensitive but must match the registered identifiers.

from aspose_barcode_foss import BarcodeService

service = BarcodeService()

# Correct symbology names
barcode = service.generate("code128", "ABC-123")
barcode = service.generate("qrcode", "https://example.com")

RenderingError

RenderingError is raised when the renderer fails to produce output from an encoded symbol.

Typical causes:

  • Invalid RenderOptions values (e.g. negative scale or module_width)
  • Attempting to use PdfRenderer (PDF rendering raises NotImplementedError in the current version)

Fix: Use SvgRenderer or PngRenderer instead of PdfRenderer. Verify that RenderOptions properties have valid positive values.

from aspose_barcode_foss import BarcodeService, RenderOptions
from aspose_barcode_foss.rendering import SvgRenderer

service = BarcodeService()
barcode = service.generate("ean13", "590123412345")

options = RenderOptions(scale=2.0, dpi=300)
result = barcode.render(SvgRenderer(), options)

UnsupportedCapabilityError and UnsupportedFeatureError

UnsupportedCapabilityError is raised when a symbology does not support a requested capability (e.g. GS1 mode for a symbology that lacks GS1 support). UnsupportedFeatureError is raised for features not implemented in the library.

Fix: Check the symbology profile’s capabilities property to confirm which features are available. Avoid requesting GS1 mode for symbologies that do not support it.

Environment Issues

Python Version

Aspose.BarCode FOSS requires Python 3.12 or later. If you see SyntaxError or import failures, verify your Python version:

python --version

Installation Problems

If pip install aspose-barcode-foss fails, ensure pip is up to date:

pip install --upgrade pip
pip install aspose-barcode-foss

The library is pure Python with no native dependencies. If installation succeeds but imports fail, check that you are not shadowing the package with a local file named aspose_barcode_foss.py.

Import Errors

The correct import is:

import aspose_barcode_foss

or import specific classes:

from aspose_barcode_foss import BarcodeService, RenderOptions

Frequently Asked Questions

Why does my EAN-13 barcode show a different number than I entered?

EAN-13 automatically computes a check digit. If you pass 12 digits, the 13th digit is appended. If you pass 13 digits, the last digit is validated as the check digit. Use the Ean13Options allow_check_digit_input property to control this behavior.

Why does PDF output raise NotImplementedError?

PdfRenderer.render() and Barcode.to_pdf() are not yet implemented. Use Barcode.to_svg() or Barcode.to_png() instead, or render with SvgRenderer or PngRenderer directly.

How do I debug which symbology names are available?

Use SymbologyRegistry.get_definition() to check if a symbology is registered. If it raises SymbologyNotFoundError, the symbology is not available. The seven supported symbologies are: Code 128, Code 39, EAN-13, EAN-8, QR Code, UPC-A, and UPC-E.

See Also

 English