Troubleshooting

This guide covers common issues and solutions when using Complinist.

Docker Setup Issues

Cannot Pull Image

Symptom: docker pull ghcr.io/stihelc/complinist-lite:lite fails with unauthorized or not found.

Solutions:

1. Confirm Docker Desktop or Docker Engine is running
2. If the package is private, log in: docker login ghcr.io
3. Verify the image name: ghcr.io/stihelc/complinist-lite:lite

Port 3000 Already in Use

Symptom: Container fails to start because port 3000 is taken.

Solution: Map a different host port:

docker run -d --name complinist -p 3001:3000 -v complinist-data:/data ghcr.io/stihelc/complinist-lite:lite
# Open http://localhost:3001

Container Exits Immediately

Symptom: docker ps does not show the container running.

Solution:

docker logs complinist
docker rm complinist
docker run -d --name complinist -p 3000:3000 -v complinist-data:/data ghcr.io/stihelc/complinist-lite:lite

Optional License Import

The lite Docker image does not require a license to use any feature. If you have a subscription, you may optionally import a license code from your account for support tracking — this does not unlock additional features in the current build.

"Invalid License Key" (optional import)

Possible causes:

• Typo in license key
• Key already used on another installation
• Subscription expired

Solutions:

1. Double-check the key (copy/paste recommended)
2. Check subscription status at complinist.com/account
3. Contact cam@complinist.com — you can use the app without importing a license

Application Issues

App Won't Start

Symptom: Browser cannot reach localhost:3000 or container is not running.

Solutions:

1. Check Docker is running and the container is up: docker ps
2. Check system requirements:
   • Docker Desktop or Docker Engine 24+
   • Windows 10/11, macOS 11+, or Linux (Ubuntu 20.04+)
   • 8 GB RAM minimum
   • 2 GB free disk space for the image
3. Restart the container:

docker stop complinist && docker rm complinist
docker run -d --name complinist -p 3000:3000 -v complinist-data:/data ghcr.io/stihelc/complinist-lite:lite

4. Reset application data (removes projects): docker volume rm complinist-data

Blank/White Screen

Symptom: Page at localhost:3000 is blank or does not load.

Solutions:

1. Wait 30 seconds (initial container start can be slow)
2. Check container logs: docker logs complinist
3. Hard refresh the browser (Ctrl+Shift+R)

Application Freezes

Symptom: App becomes unresponsive.

Solutions:

1. Wait for current operation to complete
2. For large topologies, reduce device count
3. Close and reopen the application
4. Check system resources (RAM, CPU)

Database Issues

"Database Locked"

Symptom: Error saying database is locked.

Solutions:

1. Close all instances: Make sure only one Complinist window is open and check for background processes
2. Remove lock files (stop the container first):

docker stop complinist
# Named volume (default)
docker run --rm -v complinist-data:/data alpine sh -c "rm -f /data/complinist.db-wal /data/complinist.db-shm"
# Bind mount example
rm ./docker-data/complinist.db-wal ./docker-data/complinist.db-shm
docker start complinist

3. Restart computer if issue persists

Data Not Saving

Symptom: Changes aren't persisted.

Solutions:

1. Click Save manually (Ctrl+S)
2. Check disk space
3. Verify write permissions on data directory
4. Check for database errors in console

Lost Project Data

Symptom: Project data appears missing.

Solutions:

1. Check if viewing correct project
2. Look in backup location (if enabled)
3. Check the database file in your Docker volume or bind mount:

docker run --rm -v complinist-data:/data alpine ls -la /data/complinist.db
# Or for bind mount: ls -la ./docker-data/complinist.db

Topology Canvas

Devices Not Appearing

Symptom: Devices disappear or don't show.

Solutions:

1. Zoom out to find off-canvas devices
2. Click "Fit to View" button
3. Check if devices are outside boundary
4. Reload the project

Can't Connect Devices

Symptom: Unable to draw connections.

Solutions:

1. Ensure both devices are selected properly
2. Drag from connection point (small circle)
3. Check that devices aren't locked
4. Try zooming in

Slow Performance with Large Diagrams

Symptom: Canvas lags with many devices.

Solutions:

1. Reduce device count if possible
2. Disable animations in settings
3. Close other applications
4. Use simpler device icons

SSP Generation

PDF Won't Generate

Symptom: SSP generation fails or hangs.

Solutions:

1. Ensure all required fields are completed
2. Try generating with fewer sections
3. Check available disk space
4. Look for specific error messages

Missing Content in PDF

Symptom: Sections appear empty in generated PDF.

Solutions:

1. Verify content exists in the application
2. Check that sections aren't excluded
3. Re-enter content and try again
4. Save project before generating

Diagram Not in PDF

Symptom: Network diagram missing from SSP.

Solutions:

1. Ensure topology has at least one device
2. Check diagram is within visible bounds
3. Fit to view before generating
4. Try exporting diagram separately first

Import Issues

Terraform Import Fails

Symptom: Can't import Terraform plan.

Solutions:

1. Verify JSON format:

# Must use -json flag
terraform show -json plan.tfplan > plan.json

2. Check file validity:

cat plan.json | jq .  # Should parse without error

3. Try a simpler plan to isolate the issue

CSV Import Fails

Symptom: Inventory import fails.

Solutions:

1. Download and use the template
2. Check for special characters in data
3. Ensure required columns are present
4. Try fewer rows first

Updating the Image

Pull a Newer Version

Symptom: You want the latest lite image.

Solution:

docker pull ghcr.io/stihelc/complinist-lite:lite
docker stop complinist && docker rm complinist
docker run -d --name complinist -p 3000:3000 -v complinist-data:/data ghcr.io/stihelc/complinist-lite:lite

Your data persists in the complinist-data volume unless you remove it.

Getting Help

Information to Collect

When contacting support, provide:

1. Operating system and version
2. Complinist version (from image tag or Help > About)
3. Docker setup (named volume vs bind mount)
4. Error messages (screenshots helpful)
5. Steps to reproduce the issue
6. Log files if available

Container Logs

docker logs complinist --tail 200

Contact Support

• Email: cam@complinist.com
• Include: OS, version, error details, logs

Quick Fixes Summary