Troubleshooting Guide

​

Installation Issues

​

Issue: Cython compilation fails

error: Microsoft Visual C++ 14.0 or greater is required

error: command 'gcc' failed with exit status 1

# Install Visual C++ Build Tools
# Download from: https://visualstudio.microsoft.com/visual-cpp-build-tools/

xcode-select --install

sudo apt-get install build-essential python3-dev  # Debian/Ubuntu
sudo yum install gcc gcc-c++ python3-devel        # RHEL/CentOS

pip install myspellchecker --no-build-isolation

​

Issue: OpenMP not found on macOS

clang: error: unsupported option '-fopenmp'

brew install libomp
export LDFLAGS="-L/opt/homebrew/opt/libomp/lib"
export CPPFLAGS="-I/opt/homebrew/opt/libomp/include"
pip install myspellchecker --force-reinstall

DISABLE_OPENMP=1 pip install myspellchecker

​

Issue: pip install hangs

1. Wait longer (up to 10 minutes on slow systems)
2. Check CPU usage to confirm compilation is active
3. Try installing with verbose output:
   pip install myspellchecker -v
   

​

Issue: Module not found after installation

ModuleNotFoundError: No module named 'myspellchecker'

# Check Python environment
which python
python --version

# Verify installation
pip show myspellchecker

# Reinstall if needed
pip uninstall myspellchecker
pip install myspellchecker

​

Database Issues

​

Issue: Database not found

MissingDatabaseError: Database not found at path

1. Build the database:
   myspellchecker build --sample  # Creates sample database
   
2. Specify correct path:
   from myspellchecker import SpellChecker
   from myspellchecker.providers import SQLiteProvider
   
   provider = SQLiteProvider(database_path="/path/to/your/database.db")
   checker = SpellChecker(provider=provider)
   

​

Issue: Database locked

sqlite3.OperationalError: database is locked

1. Use different database instances for each process
2. Use Memory provider for multi-process scenarios:
   from myspellchecker.providers import MemoryProvider
   checker = SpellChecker(provider=MemoryProvider())
   
3. Increase SQLite timeout:
   from myspellchecker.providers import SQLiteProvider
   provider = SQLiteProvider(database_path=db_path, sqlite_timeout=60)
   

​

Issue: Database corrupted

sqlite3.DatabaseError: database disk image is malformed

# Rebuild the database
myspellchecker build --input corpus.txt --output new_dict.db

# Or recover using sqlite3
sqlite3 corrupted.db ".recover" | sqlite3 recovered.db

​

Performance Issues

​

Issue: Spell checking is slow

1. Check Cython compilation:
   python setup.py build_ext --inplace
   
2. Use faster validation level (per-check):
   from myspellchecker.core.constants import ValidationLevel
   
   result = checker.check(text, level=ValidationLevel.SYLLABLE)
   
3. Disable context checking:
   config = SpellCheckerConfig(use_context_checker=False)
   
4. Use batch processing:
   results = checker.check_batch(texts)  # Much faster for multiple texts
   
5. Warm up the checker:
   checker = SpellChecker()
   checker.check("warmup")  # Load everything into memory
   

​

Issue: High memory usage

1. Use SQLite provider (default):
   from myspellchecker import SpellChecker
   from myspellchecker.providers import SQLiteProvider
   
   provider = SQLiteProvider(database_path="/path/to/dictionary.db")
   checker = SpellChecker(provider=provider)
   
2. Disable semantic checking:
   from myspellchecker.core.config import SpellCheckerConfig, SemanticConfig
   
   config = SpellCheckerConfig(
       semantic=SemanticConfig(use_semantic_refinement=False)
   )
   
3. Use lighter POS tagger:
   from myspellchecker.core.config import SpellCheckerConfig, POSTaggerConfig
   
   config = SpellCheckerConfig(
       pos_tagger=POSTaggerConfig(tagger_type="viterbi")
   )
   

​

Issue: Batch processing crashes

MemoryError: Unable to allocate array

# Process in smaller batches
def chunked_check(texts, batch_size=100):
    results = []
    for i in range(0, len(texts), batch_size):
        batch = texts[i:i + batch_size]
        results.extend(checker.check_batch(batch))
    return results

​

Validation Issues

​

Issue: Valid word marked as error

1. Check if word is in dictionary:
   from myspellchecker.providers import SQLiteProvider
   
   provider = SQLiteProvider(database_path="/path/to/dictionary.db")
   exists = provider.is_valid_word("မြန်မာ")
   
2. Add to custom dictionary: Rebuild with expanded corpus
3. Lower phonetic suggestion threshold:
   from myspellchecker.core.config import SpellCheckerConfig, PhoneticConfig
   
   config = SpellCheckerConfig(
       phonetic=PhoneticConfig(suggestion_threshold_unseen=0.0005)
   )
   

​

Issue: Errors not detected

1. Enable context checking:
   from myspellchecker.core.config import SpellCheckerConfig
   from myspellchecker.core.constants import ValidationLevel
   
   config = SpellCheckerConfig(use_context_checker=True)
   checker = SpellChecker(config=config)
   result = checker.check(text, level=ValidationLevel.WORD)
   
2. Enable rule-based validation:
   config = SpellCheckerConfig(use_rule_based_validation=True)
   

​

Issue: Wrong suggestions

1. Reduce max edit distance:
   config = SpellCheckerConfig(max_edit_distance=1)  # Default is 2
   
2. Increase suggestion count:
   config = SpellCheckerConfig(max_suggestions=10)
   
3. Build domain-specific dictionary: Use corpus matching your content type

​

Encoding Issues

​

Issue: Zawgyi text not detected

1. Lower detection threshold:
   from myspellchecker.text.normalize import detect_encoding
   encoding, confidence = detect_encoding(text)
   if confidence > 0.6:  # Lower threshold
       # Handle as Zawgyi
   
2. Force Zawgyi conversion:
   from myspellchecker.text.normalize import convert_zawgyi_to_unicode
   unicode_text = convert_zawgyi_to_unicode(text)  # Force conversion
   

​

Issue: Unicode normalization problems

from myspellchecker.text.normalize import normalize

# Always normalize before checking
normalized = normalize(text)
result = checker.check(normalized)

​

Issue: Mixed encoding in text

from myspellchecker.text.normalize import detect_encoding, convert_zawgyi_to_unicode

# Detect and convert if needed
encoding, confidence = detect_encoding(text)
if encoding == "zawgyi" and confidence > 0.5:
    text = convert_zawgyi_to_unicode(text)
result = checker.check(text)

​

Model Issues

​

Issue: Semantic model fails to load

ModelLoadError: Failed to load semantic model

1. Install ONNX runtime:
   pip install onnxruntime
   
2. Check model file exists:
   import os
   model_path = config.semantic.model_path
   if model_path:
       print(os.path.exists(model_path))
   
3. Disable semantic checking:
   from myspellchecker.core.config import SpellCheckerConfig, SemanticConfig
   
   config = SpellCheckerConfig(
       semantic=SemanticConfig(use_semantic_refinement=False)
   )
   

​

Issue: Transformer model OOM

RuntimeError: CUDA out of memory

1. Use CPU instead:
   from myspellchecker.core.config import SpellCheckerConfig, POSTaggerConfig
   
   config = SpellCheckerConfig(
       pos_tagger=POSTaggerConfig(device=-1)  # -1 for CPU
   )
   
2. Use smaller model or Viterbi tagger:
   from myspellchecker.core.config import SpellCheckerConfig, POSTaggerConfig
   
   config = SpellCheckerConfig(
       pos_tagger=POSTaggerConfig(tagger_type="viterbi")
   )
   

​

CLI Issues

​

Issue: Command not found

bash: myspellchecker: command not found

1. Check installation:
   pip show myspellchecker
   
2. Use the CLI entry point directly:
   myspellchecker --help
   
   Alternatively, use python -m myspellchecker which is also supported.
3. Add scripts to PATH:
   export PATH="$PATH:$(python -c 'import site; print(site.USER_BASE)')/bin"
   

​

Issue: Build command fails

Error: Input file not found

1. Use absolute path:
   myspellchecker build --input /full/path/to/corpus.txt
   
2. Check file format: Ensure UTF-8 encoding with Myanmar text
3. Verify permissions:
   ls -la corpus.txt
   

​

Getting More Help

1. Enable debug logging:
   from myspellchecker.utils.logging_utils import configure_logging
   configure_logging(level="DEBUG")
   
2. Check GitHub Issues: Search existing issues for similar problems
3. Open a new issue with:
   • Python version
   • mySpellChecker version
   • Full error traceback
   • Minimal reproduction code
   • Expected vs actual behavior

​

See Also

• FAQ - Frequently asked questions
• Error Codes - Error code reference
• Configuration - Configuration options