🔧 Troubleshooting¶

This guide will help you resolve common issues that you might encounter while using CellMage.

🚫 Common Issues & Solutions¶

API Connection Issues¶

Symptom: Unable to connect to API or Authentication failed errors.

Solutions:

Verify your API key is set correctly:

%llm_config --status  # Check if API key is set

Check that your API base URL is correct if using a custom endpoint:
```
%llm_config --api-base https://your-custom-endpoint
```
Check your internet connection and any required VPN settings.
Verify that the service isn’t experiencing an outage.

Missing Personas or Snippets¶

Symptom: Persona not found or Snippet not found errors.

Solutions:

Check your persona/snippet directories configuration:

%llm_config --status  # View configured directories

Verify that the persona/snippet exists in the specified directory:

ls ./llm_personas/  # List available personas
ls ./llm_snippets/  # List available snippets

Try using the absolute path to your persona/snippet:
```
%llm --persona /absolute/path/to/persona.md
```

SQLite Storage Issues¶

Symptom: Database errors or missing conversations.

Solutions:

Check permissions on the SQLite database file:
```
ls -la ~/.cellmage/conversations.db
```
Ensure the directory exists:
```
mkdir -p ~/.cellmage
```

Verify database integrity:

sqlite3 ~/.cellmage/conversations.db "PRAGMA integrity_check;"

Integration Authentication Problems¶

Symptom: Authentication failed when using Jira, Confluence, GitHub, or GitLab.

Solutions:

Verify that the required environment variables are set:

import os
print("JIRA_API_TOKEN set:", bool(os.environ.get("JIRA_API_TOKEN")))
# Similar for other service tokens

Check that URLs are correctly formatted (include https://):

print(os.environ.get("JIRA_URL"))  # Should start with https://

Regenerate your API tokens/PATs if they might have expired.

Kernel Restart Required¶

Symptom: Magic commands not working, incorrect behavior after changing configuration.

Solutions:

Restart the Jupyter kernel:
```
Kernel > Restart
```
Reinstall the CellMage extension:
```
%reload_ext cellmage
```

Memory Usage Issues¶

Symptom: High memory usage or kernel crashes with large prompts.

Solutions:

Use streaming responses to reduce memory footprint:
```
%llm --stream "Your prompt here"
```
Reduce context size by being more selective with snippets:
```
%llm --clear-snippets  # Clear existing snippets
```
Use smaller models when possible:
```
%llm_config --model gpt-4o-mini
```

🛠️ Base Directory Configuration & Migration¶

CellMage now supports a single environment variable, CELLMAGE_BASE_DIR, to control the base directory for all working files (personas, snippets, .data, logs, etc.).

By default, this is the current working directory.

To change it, set the environment variable:

export CELLMAGE_BASE_DIR=/path/to/your/project

All working files will be created/accessed under this directory.
To migrate, move your existing llm_personas, llm_snippets, .data, and cellmage.log into the new base directory.

Backward Compatibility: If CELLMAGE_BASE_DIR is not set, CellMage will continue to use the current working directory as before.

📝 Debugging Tips¶

Enable Debug Logging¶

To get more detailed logs:

import logging
from cellmage.utils.logging import setup_logging
setup_logging(level=logging.DEBUG)

Logs will be written to cellmage.log in your working directory.

Inspect API Requests¶

To see the exact requests being sent to the LLM API:

%llm_config --debug-mode True

This will print the full request and response objects to the log.

Check Token Usage¶

To monitor your token usage:

%llm_stats  # Shows token usage statistics

🆘 Getting Help¶

If you’re still encountering issues:

Check our GitHub Issues to see if your problem has been reported.
Create a new issue with:
- A minimal reproducible example
- Your environment details (OS, Python version, etc.)
- Full error messages and logs
- Steps you’ve already tried

Our magical community will do its best to help you resolve the issue!