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

3. Check license status:

curl http://localhost:8000/api/v3/admin/on-prem/license

4. If expired, contact Scriptix for a renewed license
5. 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:

Symptom	Cause	Fix
Jobs stay in "Uploaded"	Batch scheduler can't access Docker socket	Verify /var/run/docker.sock is mounted
ASR container exits immediately	Image not found	Verify scriptix-asr image exists: docker images | grep scriptix-asr
ASR container OOM killed	Not enough RAM	Reduce max_concurrent_jobs in config or add more RAM
Jobs fail with storage error	MinIO unreachable from ASR container	Check 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
• DB_PASSWORD was changed after the pg-data volume already existed. Postgres only applies DB_PASSWORD when it first initialises an empty data directory. If you edited it later (e.g. after a test run), the volume still holds the old password and the API logs FATAL: password authentication failed for user "scriptix".
  • No data to keep: docker compose ... down -v then up -d to re-initialise from scratch (this wipes all data).
  • Data to keep: set DB_PASSWORD back to the original, or rotate it inside Postgres with ALTER USER scriptix WITH PASSWORD '...' and update .env.onprem to match.
• 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