Troubleshooting Guide

Solutions for installation failures, database issues, performance problems, validation errors, and encoding quirks.

Organized by category — find your issue below and follow the solution. If your problem isn’t covered, see Getting More Help at the bottom.

Installation Issues

Issue: Cython compilation fails

Symptoms:

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

or

error: command 'gcc' failed with exit status 1

Cause: Missing C++ compiler for Cython extensions.

Solution:

Windows:

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

macOS:

xcode-select --install

Linux:

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

Alternative: Install without Cython (slower but works):

pip install myspellchecker --no-build-isolation

---

Issue: OpenMP not found on macOS

Symptoms:

clang: error: unsupported option '-fopenmp'

Cause: macOS clang doesn’t include OpenMP by default.

Solution:

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

Or install without OpenMP (parallel processing disabled):

DISABLE_OPENMP=1 pip install myspellchecker

---

Issue: pip install hangs

Symptoms: Installation appears to freeze during Cython compilation.

Cause: Compiling large Cython files takes time, especially on slower systems.

Solution:

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

Symptoms:

ModuleNotFoundError: No module named 'myspellchecker'

Cause: Wrong Python environment or failed installation.

Solution:

# 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

Symptoms:

XS001: Database not found at path

Cause: Default database doesn’t exist or path is wrong.

Solution:

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

Symptoms:

sqlite3.OperationalError: database is locked

Cause: Multiple processes accessing the same SQLite database.

Solution:

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

Symptoms:

sqlite3.DatabaseError: database disk image is malformed

Cause: Interrupted write operation or disk error.

Solution:

# 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

Symptoms: Checking takes >1 second for short text.

Cause: Various factors affecting performance.

Solutions:

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

Symptoms: Application uses excessive RAM.

Cause: Memory provider or large models loaded.

Solutions:

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

Symptoms:

MemoryError: Unable to allocate array

Cause: Trying to process too many texts at once.

Solution:

# 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

Symptoms: Known correct words flagged as unknown.

Cause: Word not in dictionary.

Solutions:

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

Symptoms: Misspelled words pass validation.

Cause: Validation level too low or real-word error.

Solutions:

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

Symptoms: Suggestions are irrelevant or incorrect.

Cause: Edit distance too high or corpus mismatch.

Solutions:

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

Symptoms: Zawgyi text processed as Unicode (garbled output).

Cause: Detection confidence too low.

Solutions:

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

Symptoms: Same-looking text gives different results.

Cause: Non-normalized Unicode text.

Solution:

from myspellchecker.text.normalize import normalize

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

---

Issue: Mixed encoding in text

Symptoms: Partial garbled output.

Cause: Text contains both Unicode and Zawgyi.

Solution:

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

Symptoms:

XS004: Failed to load semantic model

Cause: Missing ONNX runtime or model file.

Solutions:

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

Symptoms:

RuntimeError: CUDA out of memory

Cause: GPU memory insufficient for transformer model.

Solutions:

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

Symptoms:

bash: myspellchecker: command not found

Cause: CLI not in PATH.

Solutions:

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

Symptoms:

Error: Input file not found

Cause: Incorrect file path or format.

Solutions:

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

If your issue isn’t covered here:

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