Troubleshooting Guide¶

Common issues and solutions for SteadyText.

Installation Issues¶

Model Download Problems¶

Issue: Models fail to download automatically

Solutions: 1. Enable model downloads:

export STEADYTEXT_ALLOW_MODEL_DOWNLOADS=true

Check internet connection and firewall settings
Manually download models:
```
st models preload --size small
```

Clear model cache and retry:

st cache clear
rm -rf ~/.cache/steadytext/models/

Permission Errors¶

Issue: Permission denied errors when installing or running

Solutions: 1. Install in user directory:

pip install --user steadytext

Use virtual environment:

python -m venv steadytext-env
source steadytext-env/bin/activate  # Linux/macOS
# or
steadytext-env\Scripts\activate  # Windows
pip install steadytext

Fix cache directory permissions:

sudo chown -R $USER ~/.cache/steadytext

Runtime Issues¶

Memory Problems¶

Issue: Out of memory errors or high memory usage

Solutions: 1. Reduce cache sizes:

export STEADYTEXT_GENERATION_CACHE_CAPACITY=64
export STEADYTEXT_GENERATION_CACHE_MAX_SIZE_MB=10.0
export STEADYTEXT_EMBEDDING_CACHE_CAPACITY=128
export STEADYTEXT_EMBEDDING_CACHE_MAX_SIZE_MB=20.0

Use smaller models:

import steadytext
text = steadytext.generate("prompt", size="small")

Disable daemon mode:
```
export STEADYTEXT_DISABLE_DAEMON=true
```
Use memory cache backend:
```
export STEADYTEXT_CACHE_BACKEND=memory
```

Context Length Exceeded¶

Issue: ContextLengthExceededError when generating text

Solutions: 1. Reduce input length or split into smaller chunks

Increase context window:

export STEADYTEXT_MAX_CONTEXT_WINDOW=8192

Use streaming generation for long outputs:

import steadytext
for chunk in steadytext.generate_iter("long prompt"):
    print(chunk, end="", flush=True)

Slow Performance¶

Issue: Generation or embedding is slow

Solutions: 1. Enable daemon mode (if not already enabled):

st daemon start

Increase cache capacity:

export STEADYTEXT_GENERATION_CACHE_CAPACITY=512
export STEADYTEXT_EMBEDDING_CACHE_CAPACITY=1024

Use smaller models for better speed:

text = steadytext.generate("prompt", size="small")

Preload models:
```
st models preload --size small
```

Daemon Issues¶

Connection Problems¶

Issue: Cannot connect to daemon

Solutions: 1. Check if daemon is running:

st daemon status

Start daemon:
```
st daemon start
```

Check daemon configuration:

export STEADYTEXT_DAEMON_HOST=localhost
export STEADYTEXT_DAEMON_PORT=5557

Restart daemon:
```
st daemon restart
```

Daemon Crashes¶

Issue: Daemon process terminates unexpectedly

Solutions: 1. Check daemon logs:

st daemon status --json

Start daemon in foreground for debugging:
```
st daemon start --foreground
```

Clear daemon state:

st daemon stop --force
st cache clear
st daemon start

PostgreSQL Extension Issues¶

Extension Not Loading¶

Issue: PostgreSQL extension fails to load

Solutions: 1. Check PostgreSQL logs for error messages

Ensure Python and SteadyText are properly installed:

sudo -u postgres python3 -c "import steadytext; print('OK')"

Check plpython3u extension:

CREATE EXTENSION IF NOT EXISTS plpython3u;

Reinstall extension:

cd pg_steadytext
make clean
make install

Python Path Issues¶

Issue: Python modules not found in PostgreSQL

Solutions: 1. Set Python path in PostgreSQL:

ALTER SYSTEM SET plpython3.python_path = '/path/to/steadytext/venv/lib/python3.x/site-packages';
SELECT pg_reload_conf();

Use virtual environment path:

# Find the correct path
python3 -c "import steadytext; print(steadytext.__file__)"

Async Worker Issues¶

Issue: Async functions not working

Solutions: 1. Check worker status:

SELECT * FROM steadytext_queue_status();

Restart worker:

sudo systemctl restart steadytext-worker

Check worker logs:

sudo journalctl -u steadytext-worker -f

Cache Issues¶

Cache Corruption¶

Issue: Cache returns invalid results

Solutions: 1. Clear all caches:

st cache clear

Reset cache directory:
```
rm -rf ~/.cache/steadytext/
```
Switch to memory backend temporarily:
```
export STEADYTEXT_CACHE_BACKEND=memory
```

Cache Size Problems¶

Issue: Cache files growing too large

Solutions: 1. Reduce cache limits:

export STEADYTEXT_GENERATION_CACHE_MAX_SIZE_MB=25.0
export STEADYTEXT_EMBEDDING_CACHE_MAX_SIZE_MB=50.0

Regular cache cleanup:

st cache status  # Check current usage
st cache clear   # Clear if needed

Shell Integration Issues¶

Completion Not Working¶

Issue: Tab completion not functioning

Solutions: 1. Reinstall completions:

st completion --install

Restart shell or source configuration:

source ~/.bashrc  # Bash
source ~/.zshrc   # Zsh

Check completion installation:

st completion --shell zsh  # Generate completion script

ZSH Plugin Issues¶

Issue: ZSH suggestions not working

Solutions: 1. Check plugin configuration:

echo $STEADYTEXT_SUGGEST_ENABLED

Enable suggestions:
```
export STEADYTEXT_SUGGEST_ENABLED=1
```
Restart ZSH:
```
exec zsh
```

Development Issues¶

Testing Problems¶

Issue: Tests fail or hang

Solutions: 1. Allow model downloads for tests:

STEADYTEXT_ALLOW_MODEL_DOWNLOADS=true python -m pytest

Use memory cache for tests:

STEADYTEXT_CACHE_BACKEND=memory python -m pytest

Skip model-dependent tests:
```
python -m pytest -k "not test_model"
```

Import Errors¶

Issue: Cannot import steadytext modules

Solutions: 1. Check installation:

pip list | grep steadytext

Reinstall in development mode:
```
pip install -e .
```

Check Python path:

python -c "import sys; print(sys.path)"

Getting Help¶

If you continue to experience issues:

Check the FAQ for common questions
Review the Configuration Guide for advanced settings
Open an issue on GitHub
Include error messages, system information, and configuration details

Debug Information¶

To gather debug information:

# System information
uname -a
python --version
pip list | grep steadytext

# SteadyText status
st --version
st daemon status
st cache status

# Environment variables
env | grep STEADYTEXT

Include this information when reporting issues.