Skip to main content
This guide covers common issues you might encounter when using Panlabel and how to resolve them.

​
Format Detection Issues

Problem: Panlabel can’t automatically determine your input format.Solution: Explicitly specify the format using the --from flag:
# Instead of --from auto, specify the format
panlabel convert --from coco --to yolo -i input.json -o output
Common causes:
  • File extension doesn’t match the format (e.g., .txt instead of .json for COCO)
  • File structure doesn’t match expected layout
  • Malformed or incomplete annotation file
Problem: Your YOLO directory isn’t recognized as a valid dataset.Solution: Ensure your YOLO dataset follows the expected structure:
dataset/
├── images/
│   ├── train/
│   │   ├── img1.jpg
│   │   └── img2.jpg
│   └── val/
├── labels/
│   ├── train/
│   │   ├── img1.txt
│   │   └── img2.txt
│   └── val/
└── data.yaml  # or classes.txt
Requirements:
  • images/ and labels/ directories must exist
  • Either data.yaml or classes.txt must be present
  • Label files must have matching names to image files
Problem: Your Pascal VOC directory isn’t recognized.Solution: Ensure your VOC dataset has the required structure:
dataset/
├── Annotations/
│   ├── img1.xml
│   └── img2.xml
└── JPEGImages/  # or ImageSets/
Requirements:
  • Annotations/ directory must exist with XML files
  • Either JPEGImages/ or ImageSets/ directory should be present

​
Validation Errors

Problem: Dataset contains duplicate image, category, or annotation IDs.
Error: Validation failed
- Duplicate image IDs: [42, 100]
Solution: Fix duplicate IDs in your source data. Each ID must be unique within its type:
# First, identify the duplicates
panlabel validate --format coco input.json

# Fix the IDs in your source file, then validate again
panlabel validate --format coco fixed.json
Problem: Annotations reference image or category IDs that don’t exist.
Error: Annotation 10 references missing image ID 99
Solution: Ensure all referenced IDs exist in the dataset:
  • Check that all image_id values in annotations match actual image IDs
  • Check that all category_id values in annotations match actual category IDs
  • Remove orphaned annotations or add missing images/categories
Problem: Bounding boxes have invalid coordinates or dimensions.
Error: Invalid bbox: negative width or height
Solution: Fix the bounding box coordinates:Common issues:
  • Negative width or height: x_max must be greater than x_min, y_max greater than y_min
  • Coordinates outside image bounds: ensure 0 <= x <= image_width and 0 <= y <= image_height
  • Zero-area boxes: width and height must be positive
# Validate to find all invalid boxes
panlabel validate --format coco input.json
Problem: Dataset has no images, categories, or annotations.Solution: Ensure your dataset contains the required elements:
  • At least one image
  • At least one category
  • Optionally, annotations (some formats allow empty annotation lists)
# Check dataset statistics first
panlabel stats --format coco input.json

​
Conversion Issues

Problem: The conversion would lose data and needs explicit confirmation.
Error: Conversion would lose data. Use --allow-lossy to proceed.
Solution: Review what will be lost, then add --allow-lossy if acceptable:
# First, check the conversion report
panlabel convert -f coco -t yolo -i input.json -o output --report json

# If the losses are acceptable, allow lossy conversion
panlabel convert -f coco -t yolo -i input.json -o output --allow-lossy
See the Lossiness guide for details on what each format preserves.
Problem: The output path already contains files.Solution: Either remove the existing output or choose a different path:
# Remove existing output
rm -rf output_dir/

# Or use a different output path
panlabel convert -f coco -t yolo -i input.json -o new_output_dir/
Problem: Multiple YOLO class map sources with conflicting information.Solution: Ensure consistency between data.yaml and classes.txt:
# data.yaml
names:
  0: person
  1: car
  2: dog

# classes.txt (same order)
person
car
dog
Precedence: data.yaml > classes.txt > inferred from label files
Problem: Rotated bounding boxes are converted to axis-aligned boxes.Solution: This is expected behavior. Label Studio rotated boxes are flattened to their axis-aligned envelopes:
  • The original rotation angle is preserved in the ls_rotation_deg attribute
  • The bounding box becomes the smallest axis-aligned rectangle that contains the rotated box
  • You’ll see a warning in the conversion report
panlabel convert -f label-studio -t coco -i input.json -o output.json --allow-lossy

​
File I/O Issues

Problem: Can’t read input file or write to output location.Solution: Check file and directory permissions:
# Check input file permissions
ls -l input.json

# Ensure output directory is writable
ls -ld output_dir/

# Fix permissions if needed
chmod 644 input.json
chmod 755 output_dir/
Problem: Input file or directory doesn’t exist.Solution: Verify the path is correct:
# Use absolute paths to avoid confusion
panlabel convert -f coco -t yolo \
  -i /full/path/to/input.json \
  -o /full/path/to/output/

# Or use ls to verify the file exists
ls -l input.json
Problem: Input file contains invalid JSON or XML.
Error: Failed to parse COCO JSON: expected `,` or `}` at line 42
Solution: Validate and fix your JSON/XML:
# Validate JSON
jq . input.json > /dev/null

# Validate XML
xmllint --noout input.xml

# Pretty-print and fix formatting
jq . input.json > formatted.json

​
Performance Issues

Problem: Large dataset conversion takes a long time.Solution: This is expected for very large datasets. Tips to improve performance:
  • Use release builds: cargo build --release
  • Convert to IR JSON first, then to the target format (two-step conversion)
  • Split large datasets into smaller chunks
# Two-step conversion can be faster for multiple outputs
panlabel convert -f coco -t ir-json -i huge.json -o intermediate.json
panlabel convert -f ir-json -t yolo -i intermediate.json -o yolo_out/
panlabel convert -f ir-json -t voc -i intermediate.json -o voc_out/
Problem: Panlabel crashes or system runs out of memory.Solution: Large datasets require significant memory. Options:
  • Use the sample command to work with a subset first
  • Increase available system memory
  • Split the dataset into smaller parts
# Work with a sample first
panlabel sample -f coco -i huge.json -o sample.json -n 1000 --seed 42

# Process the sample
panlabel convert -f coco -t yolo -i sample.json -o yolo_sample/

​
Getting Help

If you encounter an issue not covered here:
  1. Check the CLI reference for command-specific options
  2. Run panlabel <command> --help for detailed usage information
  3. Open an issue on GitHub with:
    • The command you ran
    • The error message
    • A minimal example that reproduces the problem

Build docs developers (and LLMs) love

Get started for freeTalk to us