Community Edition | Enterprise Edition

Troubleshooting SWIRL

Understanding `.swirl`

The swirl.py control script tracks running services and their process IDs (PIDs) in a file called .swirl.

Example `.swirl` File

For a fully running system, the file looks like this:

{"django": 26391, "celery-worker": 26424}

How `.swirl` Works

The .swirl file is read by the status and stop commands to check running processes.
These commands use ps -p with stored PIDs to determine whether services are running.

If you manually start or stop services, the .swirl file updates accordingly.

Fixing Out-of-Sync `.swirl` Files

If the .swirl file does not match the actual running processes:

Delete the file: rm .swirl.
Restart SWIRL to regenerate it.
Manually stop any remaining SWIRL processes before restarting.

Finding SWIRL Processes

To check for running SWIRL processes, use the following commands:

On macOS or Linux:

ps -ef | grep daphne
ps -ef | grep celery
ps -ef | grep redis

Logs

All SWIRL services write logs to the logs/ folder inside swirl-search.

Log Files Overview

Logfile	Description	Notes
`logs/django.log`	Logs Django container activity, including all API calls.	Not involved in query federation.
`logs/celery-worker.log`	Logs Celery tasks, including search federation.	Look for errors in `search.status` or partial results.
`logs/celery-beats.log`	Logs the Celery Beats service used for search expiration and subscription.	Check here if subscriptions or expirations are not working.

Viewing Logs

To continuously view logs, run:

python swirl.py logs/

This displays live log output from all SWIRL services.

Example Log Entry (INFO Level)

2023-08-02 10:49:09,466 INFO     admin search 452 FULL_RESULTS_READY 32 2.2

For detailed logging, enable debug mode:

Restart SWIRL with the --debug flag, or
Update settings.py (see the Developer Guide for details).

Common Enterprise Issues

License Validation Errors

If you see license validation errors in logs/django.log:

Verify the SWIRL_LICENSE value in your .env file is valid JSON.
Check that the license has not expired (the expiration field is a date in YYYY-MM-DD format).
Ensure the public_key.pem file is present in the SWIRL installation directory.
Contact support if the issue persists.

Celery Workers Not Starting

SWIRL Enterprise runs five specialized Celery workers. If any fail to start:

Check logs/celery-*.log for error messages.
Verify Redis is running and accessible at the configured CELERY_BROKER_URL.
Check available system memory — each worker requires its own process pool.
Run python swirl.py status to see which workers are running.

RAG Timeout or No Response

If Generate AI Insight times out:

Verify your AI Provider is configured and active at /swirl/aiproviders/.
Check that the API key in the AI Provider credentials is valid.
Increase SWIRL_RAG_TIMEOUT in .env for large document sets.
Check logs/celery-pagefetch-worker.log for page-fetching errors.
Ensure the Tika service is running if processing PDF or Office documents.