> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myspellchecker.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](#getting-more-help) at the bottom.

## Installation Issues

### Issue: Cython compilation fails

**Symptoms**:

```yaml theme={null}
error: Microsoft Visual C++ 14.0 or greater is required
```

or

```python theme={null}
error: command 'gcc' failed with exit status 1
```

**Cause**: Missing C++ compiler for Cython extensions.

**Solution**:

**Windows**:

```bash theme={null}
# Install Visual C++ Build Tools
# Download from: https://visualstudio.microsoft.com/visual-cpp-build-tools/
```

**macOS**:

```bash theme={null}
xcode-select --install
```

**Linux**:

```bash theme={null}
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):

```bash theme={null}
pip install myspellchecker --no-build-isolation
```

***

### Issue: OpenMP not found on macOS

**Symptoms**:

```yaml theme={null}
clang: error: unsupported option '-fopenmp'
```

**Cause**: macOS clang doesn't include OpenMP by default.

**Solution**:

```bash theme={null}
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):

```bash theme={null}
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:
   ```bash theme={null}
   pip install myspellchecker -v
   ```

***

### Issue: Module not found after installation

**Symptoms**:

```python theme={null}
ModuleNotFoundError: No module named 'myspellchecker'
```

**Cause**: Wrong Python environment or failed installation.

**Solution**:

```bash theme={null}
# 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**:

```
MissingDatabaseError: Database not found at path
```

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

**Solution**:

1. **Build the database**:
   ```bash theme={null}
   myspellchecker build --sample  # Creates sample database
   ```

2. **Specify correct path**:
   ```python theme={null}
   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**:

```python theme={null}
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:
   ```python theme={null}
   from myspellchecker.providers import MemoryProvider
   checker = SpellChecker(provider=MemoryProvider())
   ```
3. **Increase SQLite timeout**:
   ```python theme={null}
   from myspellchecker.providers import SQLiteProvider
   provider = SQLiteProvider(database_path=db_path, sqlite_timeout=60)
   ```

***

### Issue: Database corrupted

**Symptoms**:

```python theme={null}
sqlite3.DatabaseError: database disk image is malformed
```

**Cause**: Interrupted write operation or disk error.

**Solution**:

```bash theme={null}
# 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**:
   ```bash theme={null}
   python setup.py build_ext --inplace
   ```

2. **Use faster validation level** (per-check):
   ```python theme={null}
   from myspellchecker.core.constants import ValidationLevel

   result = checker.check(text, level=ValidationLevel.SYLLABLE)
   ```

3. **Disable context checking**:
   ```python theme={null}
   config = SpellCheckerConfig(use_context_checker=False)
   ```

4. **Use batch processing**:
   ```python theme={null}
   results = checker.check_batch(texts)  # Much faster for multiple texts
   ```

5. **Warm up the checker**:
   ```python theme={null}
   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):
   ```python theme={null}
   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**:
   ```python theme={null}
   from myspellchecker.core.config import SpellCheckerConfig, SemanticConfig

   config = SpellCheckerConfig(
       semantic=SemanticConfig(use_semantic_refinement=False)
   )
   ```

3. **Use lighter POS tagger**:
   ```python theme={null}
   from myspellchecker.core.config import SpellCheckerConfig, POSTaggerConfig

   config = SpellCheckerConfig(
       pos_tagger=POSTaggerConfig(tagger_type="viterbi")
   )
   ```

***

### Issue: Batch processing crashes

**Symptoms**:

```yaml theme={null}
MemoryError: Unable to allocate array
```

**Cause**: Trying to process too many texts at once.

**Solution**:

```python theme={null}
# 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**:
   ```python theme={null}
   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**:
   ```python theme={null}
   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**:
   ```python theme={null}
   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**:
   ```python theme={null}
   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**:
   ```python theme={null}
   config = SpellCheckerConfig(max_edit_distance=1)  # Default is 2
   ```

2. **Increase suggestion count**:
   ```python theme={null}
   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**:
   ```python theme={null}
   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**:
   ```python theme={null}
   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**:

```python theme={null}
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**:

```python theme={null}
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**:

```
ModelLoadError: Failed to load semantic model
```

**Cause**: Missing ONNX runtime or model file.

**Solutions**:

1. **Install ONNX runtime**:
   ```bash theme={null}
   pip install onnxruntime
   ```

2. **Check model file exists**:
   ```python theme={null}
   import os
   model_path = config.semantic.model_path
   if model_path:
       print(os.path.exists(model_path))
   ```

3. **Disable semantic checking**:
   ```python theme={null}
   from myspellchecker.core.config import SpellCheckerConfig, SemanticConfig

   config = SpellCheckerConfig(
       semantic=SemanticConfig(use_semantic_refinement=False)
   )
   ```

***

### Issue: Transformer model OOM

**Symptoms**:

```yaml theme={null}
RuntimeError: CUDA out of memory
```

**Cause**: GPU memory insufficient for transformer model.

**Solutions**:

1. **Use CPU instead**:
   ```python theme={null}
   from myspellchecker.core.config import SpellCheckerConfig, POSTaggerConfig

   config = SpellCheckerConfig(
       pos_tagger=POSTaggerConfig(device=-1)  # -1 for CPU
   )
   ```

2. **Use smaller model or Viterbi tagger**:
   ```python theme={null}
   from myspellchecker.core.config import SpellCheckerConfig, POSTaggerConfig

   config = SpellCheckerConfig(
       pos_tagger=POSTaggerConfig(tagger_type="viterbi")
   )
   ```

## CLI Issues

### Issue: Command not found

**Symptoms**:

```bash theme={null}
bash: myspellchecker: command not found
```

**Cause**: CLI not in PATH.

**Solutions**:

1. **Check installation**:
   ```bash theme={null}
   pip show myspellchecker
   ```

2. **Use the CLI entry point directly**:
   ```bash theme={null}
   myspellchecker --help
   ```
   Alternatively, use `python -m myspellchecker` which is also supported.

3. **Add scripts to PATH**:
   ```bash theme={null}
   export PATH="$PATH:$(python -c 'import site; print(site.USER_BASE)')/bin"
   ```

***

### Issue: Build command fails

**Symptoms**:

```yaml theme={null}
Error: Input file not found
```

**Cause**: Incorrect file path or format.

**Solutions**:

1. **Use absolute path**:
   ```bash theme={null}
   myspellchecker build --input /full/path/to/corpus.txt
   ```

2. **Check file format**: Ensure UTF-8 encoding with Myanmar text

3. **Verify permissions**:
   ```bash theme={null}
   ls -la corpus.txt
   ```

## Getting More Help

If your issue isn't covered here:

1. **Enable debug logging**:
   ```python theme={null}
   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](/reference/faq) - Frequently asked questions
* [Error Codes](/reference/error-codes) - Error code reference
* [Configuration](/guides/configuration) - Configuration options