Troubleshooting

Common issues and how to resolve them

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

Format Detection Issues

Auto-detection fails with 'Could not detect format'

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

YOLO dataset not detected

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

VOC dataset not detected

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

Duplicate ID 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

Missing reference errors

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

Invalid bounding box errors

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

Empty dataset errors

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

Conversion blocked with 'requires --allow-lossy'

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.

Output file already exists

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/

YOLO class map conflicts

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

Label Studio rotation flattening

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

Permission denied errors

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/

File not found errors

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

Malformed JSON/XML errors

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

Conversion is very slow

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/

Out of memory errors

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