SWIRL Docs
/
swirlaiconnect.com
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:

  1. Delete the file: rm .swirl.
  2. Restart SWIRL to regenerate it.
  3. 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 (Community). Look for errors in search.status or partial results. Enterprise runs specialized workers with their own logs: celery-search-worker.log, celery-pagefetch-worker.log, celery-interactive-worker.log, celery-maintenance-worker.log, celery-healthcheck-worker.log, and celery-corpus-worker.log.
logs/celery-beats.log Logs the Celery Beats scheduler used for search expiration, subscription, and token refresh. 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:

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

Celery Workers Not Starting

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

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

RAG Timeout or No Response

If Generate AI Insight times out:

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

Docker Deployment Issues

SWIRL 5 Enterprise runs as a Docker Compose stack: the swirl application container plus sidecar services including postgres, redis, qdrant, and tika.

Viewing Container Logs

To check service state and read logs:

docker compose ps
docker compose logs -f swirl
docker compose logs -f qdrant

The SWIRL container also writes the per-service log files described in Logs above to its internal logs/ directory.

Authenticators Missing After an Upgrade

If every Authenticator disappears from the user menu after upgrading the SWIRL image, the database has unapplied migrations. Apply them and restart:

docker compose exec swirl python manage.py migrate
docker compose restart swirl

Semantic Cache Unavailable or Clustering Not Working

If the Semantic Cache source shows an error on every search, or version clustering stops grouping documents:

  1. Verify the qdrant container is running and healthy (docker compose ps).
  2. Check logs/celery-search-worker.log in the swirl container for embedding or vector errors.
  3. If embedding errors persist after the model previously worked, restart the stack - a failed embedding-model load clears on restart.
  4. Confirm the database schema matches the image: run docker compose exec swirl python manage.py migrate.
  5. Confirm your license includes the Semantic Cache (the cache field). See the Semantic Cache Guide.

Stale Data After Recreating the Stack

Named Docker volumes persist across docker compose down / up, so a recreated stack keeps the previous database, users, and provider configuration. For a truly clean start:

docker compose down -v

Warning: down -v deletes all volumes - the database, cached documents, and vector index are permanently removed.

Ollama Provider Connection Errors

If requests to an Ollama AI Provider fail with an error like Illegal header value b'Bearer ', set a non-empty api_key on the AI Provider - any placeholder value works, since local Ollama does not check it.