Skip to main content

Troubleshooting

Common issues and solutions for Scriptix On-Prem.

Quick Diagnostics​

Run these commands to get a snapshot of your system's health:

# Service status
docker compose -f docker-compose.onprem.yml --env-file .env.onprem ps

# API health
curl http://localhost:8000/health

# Recent logs (all services)
docker compose -f docker-compose.onprem.yml --env-file .env.onprem logs --tail 50

# Specific service logs
docker compose -f docker-compose.onprem.yml --env-file .env.onprem logs --tail 100 api
docker compose -f docker-compose.onprem.yml --env-file .env.onprem logs --tail 100 batch-scheduler

Common Issues​

API returns 401 on all endpoints​

Cause: License is invalid, expired, or not configured.

Fix:

  1. Check your license configuration in config/config.local.yaml
  2. For offline licenses, verify both files exist:
ls -la config/license.json config/license_key.pub
  1. Check license status:
curl http://localhost:8000/api/v3/admin/on-prem/license
  1. If expired, contact Scriptix for a renewed license
  2. After updating the license, restart the API:
docker compose -f docker-compose.onprem.yml --env-file .env.onprem restart api

Services won't start​

Cause: Usually a dependency issue or port conflict.

Check:

# See which services are unhealthy
docker compose -f docker-compose.onprem.yml --env-file .env.onprem ps

# Check logs of the failing service
docker compose -f docker-compose.onprem.yml --env-file .env.onprem logs <service-name>

Common causes:

  • Port already in use: Error starting userland proxy: listen tcp4 0.0.0.0:80: bind: address already in use
    • Stop the conflicting service or change the port in docker-compose.onprem.yml
  • Database password mismatch between .env.onprem and config.local.yaml
  • Docker daemon not running: Cannot connect to the Docker daemon
    • Start Docker: sudo systemctl start docker

Transcription jobs stuck or failing​

Check batch scheduler logs:

docker compose -f docker-compose.onprem.yml --env-file .env.onprem logs --tail 100 batch-scheduler

Check if ASR containers are running:

docker ps | grep scriptix-asr

Common causes:

SymptomCauseFix
Jobs stay in "Uploaded"Batch scheduler can't access Docker socketVerify /var/run/docker.sock is mounted
ASR container exits immediatelyImage not foundVerify scriptix-asr image exists: docker images | grep scriptix-asr
ASR container OOM killedNot enough RAMReduce max_concurrent_jobs in config or add more RAM
Jobs fail with storage errorMinIO unreachable from ASR containerCheck batch.docker.network matches actual network name

Retry failed jobs:

# Via API (requires admin token)
curl -X POST -H "Authorization: Bearer <admin-token>" \
  http://localhost:8000/api/v3/admin/on-prem/sessions/<session-id>/retry

# Bulk retry all stranded sessions
curl -X POST -H "Authorization: Bearer <admin-token>" \
  http://localhost:8000/api/v3/admin/on-prem/sessions/bulk-retry

Services don't restart after server reboot​

Cause: Docker daemon not enabled on boot.

Fix:

sudo systemctl enable docker
sudo systemctl start docker

# Verify services came back
docker compose -f docker-compose.onprem.yml --env-file .env.onprem ps

Database connection errors​

Symptoms: API logs show connection refused or password authentication failed.

Check:

# Is the database running?
docker compose -f docker-compose.onprem.yml --env-file .env.onprem ps db

# Can you connect manually?
docker exec -it api-scriptix-db-1 psql -U scriptix -d scriptix -c "SELECT 1"

Common causes:

  • Password in config.local.yaml doesn't match DB_PASSWORD in .env.onprem
  • Database volume was deleted (docker compose down -v removes all data)
  • Database still initializing after a fresh start (wait 30 seconds)

UI loads but can't reach API​

Symptoms: UI shows loading spinners or network errors.

Check:

  1. Verify API_URL in .env.onprem matches how the browser reaches the API
  2. If using a reverse proxy, ensure it proxies to port 8000
  3. Check CORS: allowed_origins in config.local.yaml must include the UI's URL
  4. Browser console (F12) will show the exact failing request

File uploads fail​

Symptoms: Upload progress stops or errors out.

Check:

# Is storage-uploader running?
docker compose -f docker-compose.onprem.yml --env-file .env.onprem ps storage-uploader

# Check MinIO health
curl http://localhost:9000/minio/health/live

Common causes:

  • File exceeds MAX_FILE_SIZE (default 2 GB)
  • MinIO disk is full — check: docker exec api-scriptix-minio-1 df -h /data
  • If using a reverse proxy, ensure client_max_body_size is large enough (e.g., 2G)

Documents not generating​

Check:

docker compose -f docker-compose.onprem.yml --env-file .env.onprem logs --tail 50 document-creator

The document-creator service listens to RabbitMQ for completed transcriptions and generates exports. If it's not running or RabbitMQ is down, documents won't be created.

Collecting Logs for Support​

When contacting Scriptix support, include:

# Full system info
docker compose -f docker-compose.onprem.yml --env-file .env.onprem ps > diagnostics.txt
docker compose -f docker-compose.onprem.yml --env-file .env.onprem logs --tail 500 >> diagnostics.txt 2>&1

# System resources
df -h >> diagnostics.txt
free -h >> diagnostics.txt
docker system df >> diagnostics.txt

Send diagnostics.txt to info@scriptix.io along with a description of the issue.

warning

Do not include your .env.onprem or config.local.yaml — these contain passwords. If Scriptix needs configuration details, we'll ask for specific values.

Disk Space​

Check usage:

# Docker disk usage
docker system df

# Volume sizes
docker system df -v | grep -A 50 "VOLUME NAME"

Clean up unused images (safe — only removes images not used by any container):

docker image prune -f

Clean up old ASR containers that finished:

docker container prune -f