12.1. Common Errors

This page lists common errors encountered when using Tiny ML Tensorlab and their solutions.

12.1.1. Installation Errors

Python Version Error

ERROR: Package requires Python 3.10.*

Solution:

Use Python 3.10.x specifically:

pyenv install 3.10.13
pyenv local 3.10.13

Package Conflict

ERROR: Cannot install package due to conflicting dependencies

Solution:

Use a fresh virtual environment:

python -m venv venv_fresh
source venv_fresh/bin/activate
pip install -e .

TI Compiler Not Found

ERROR: ti_cgt_c2000 not found

Solution:

Set environment variable:

export TOOLS_PATH=$HOME/ti

See Environment Variables for details.

12.1.2. Dataset Errors

Dataset Not Found

ERROR: Dataset 'my_dataset' not found

Solution:

Check dataset path and name:

dataset:
  dataset_name: 'my_dataset'
  input_data_path: '/full/path/to/my_dataset'  # Absolute path

Invalid Dataset Format

ERROR: Could not parse annotations.yaml

Solution:

Verify annotations.yaml format:

name: my_dataset
description: My dataset description
task_type: classification

See Classification Dataset Format for correct format.

Missing Classes Directory

ERROR: 'classes' directory not found in dataset

Solution:

Verify directory structure:

my_dataset/
├── annotations.yaml
└── classes/           # Must be named 'classes'
    ├── class_a/
    └── class_b/

Empty CSV Files

WARNING: Empty CSV file detected: sample.csv

Solution:

Check CSV files have valid data. Minimum requirements:

  • At least one column

  • At least one row of data

  • No empty files

12.1.3. Training Errors

Out of Memory (OOM)

RuntimeError: CUDA out of memory

Solution:

Reduce batch size:

training:
  batch_size: 64  # Reduce from 256

Or use CPU:

training:
  num_gpus: 0

Model Not Found

KeyError: 'CLS_4k_NPU' not found in model registry

Solution:

Check model name spelling. List available models:

python -c "from tinyml_tinyverse.common.models import MODEL_REGISTRY; print(list(MODEL_REGISTRY.keys()))"

Feature Extraction Preset Not Found

ERROR: Feature extraction preset 'My_Preset' not found

Solution:

Use a valid preset name:

data_processing_feature_extraction:
  feature_extraction_name: 'Generic_1024Input_FFTBIN_64Feature_8Frame'

Training Loss Not Decreasing

Epoch 20: Loss 2.45 (same as epoch 1)

Solutions:

  1. Check learning rate:

    training:
  learning_rate: 0.001  # Try different values

  2. Check data preprocessing

  3. Verify labels are correct

  4. Use GoF test to check class separability

NaN Loss

Epoch 5: Loss = nan

Solutions:

  1. Lower learning rate:

    training:
  learning_rate: 0.0001

  2. Add gradient clipping

  3. Check for data issues (inf, nan values)

12.1.4. Compilation Errors

NPU Constraint Violation

ERROR: Channel count 5 not a multiple of 4

Solution:

Use NPU-compatible model:

training:
  model_name: 'CLS_4k_NPU'  # _NPU suffix models

Kernel Size Exceeds Limit

ERROR: GCONV kernel height 8 exceeds maximum 7

Solution:

Use appropriate model or modify architecture. See NPU Guidelines.

Unsupported Layer Type

ERROR: Layer type 'LSTM' not supported for target device

Solution:

Use only supported layers (Conv, Pool, FC, BN, ReLU).

Model Too Large

ERROR: Model size 80KB exceeds device Flash 64KB

Solution:

Use smaller model:

training:
  model_name: 'CLS_1k_NPU'  # Smaller model

12.1.5. Quantization Errors

Calibration Data Missing

ERROR: PTQ requires calibration data

Solution:

Provide calibration data:

training:
  quantization: 2
  quantization_method: 'PTQ'
  quantization_weight_bitwidth: 8
  quantization_activation_bitwidth: 8

Quantization Accuracy Drop

Float accuracy: 98%, INT8 accuracy: 75%

Solutions:

  1. Use QAT instead of PTQ:

    training:
  quantization: 2
  quantization_method: 'QAT'
  quantization_weight_bitwidth: 8
  quantization_activation_bitwidth: 8

  2. Try higher bit widths (8-bit instead of 4-bit or 2-bit)

  3. Use a larger model

12.1.6. Deployment Errors

CCS Import Fails

Error importing project: SDK not found

Solution:

Install required SDK:

  • C2000WARE for C2000 devices

  • MSPM0 SDK for MSPM0 devices

Linker Error: Undefined Symbol

undefined symbol: mod_inference

Solution:

Add mod.a to linker settings:

  1. Project Properties → Build → Linker → File Search Path

  2. Add library: ${PROJECT_ROOT}/model/mod.a

Runtime Hard Fault

Exception: Hard Fault at 0x00001234

Solutions:

  1. Check memory alignment

  2. Verify buffer sizes

  3. Check stack size

  4. Enable debug symbols

Wrong Inference Results

Expected class 0, got class 2 (all inputs)

Solutions:

  1. Verify input data format matches training

  2. Check preprocessing (normalization)

  3. Use test vectors to validate

  4. Compare with Python inference

12.1.7. Configuration Errors

YAML Syntax Error

yaml.scanner.ScannerError: mapping values are not allowed

Solution:

Check YAML syntax:

  • Proper indentation (spaces, not tabs)

  • Colons followed by space

  • Quotes around special characters

Missing Required Field

KeyError: 'target_device' is required

Solution:

Add required field:

common:
  target_device: 'F28P55'
  task_type: 'generic_timeseries_classification'

Invalid Device Name

ERROR: Device 'F28P55X' not supported

Solution:

Check device name spelling. Valid names:

  • F28P55, F28P65, F29H85, F29P58, F29P32

  • F2837, F28004, F28003, F280013, F280015

  • MSPM0G3507, MSPM0G3519, MSPM0G5187

  • AM263, AM263P, AM261, AM13E2

  • CC2755, CC1352

12.1.8. Getting Help

If your error isn’t listed:

  1. Check the full error traceback

  2. Search existing GitHub issues

  3. Create new issue with:

    • Full error message

    • Configuration file

    • Steps to reproduce

    • Environment details

Report issues at: https://github.com/TexasInstruments/tinyml-tensorlab/issues