Skip to main content

Troubleshooting

Can't reach the server​

A developer's scd configure or scd doctor cannot connect to scd-server.

Verify the server is up from the server machine itself:

curl http://localhost:3000/api/v1/health
# { "status": "ok", ... }

Then check from a developer machine:

curl http://your-server-ip:3000/api/v1/health

Common causes:

  • Firewall — the server's firewall is blocking the port. Open it for your internal network only.
  • Wrong bind address — host: 127.0.0.1 in config.yml restricts scd-server to the local machine. Change to host: 0.0.0.0 if developers are connecting from other machines.
  • Off-site access — developers not on the same network need VPN access. See Remote access.

Port already in use​

Port 3000 is already in use. Is scd-server already running?
Change port with: ./scd-server --port <port>  or set port in config.yml

Find what is using the port:

# Linux / macOS
lsof -i :3000

# Windows
netstat -ano | findstr :3000

Either stop the conflicting process, or change scd-server's port in config.yml.

Binary treated as a JavaScript file (Windows)​

If Windows opens scd-server-win-x64.exe with Node.js or shows a JavaScript error, run it directly from a command prompt — do not prepend node:

.\scd-server-win-x64.exe

systemd service fails to start​

Check the logs first:

sudo journalctl -u scd-server -n 50 --no-pager

ExecStart with quotes — if you see an "exec format error" or "not found" and the unit file has quotes around the ExecStart value, remove them:

# Wrong
ExecStart="/opt/scd-server/scd-server-linux-x64"

# Correct
ExecStart=/opt/scd-server/scd-server-linux-x64

After editing the unit file, always reload before restarting:

sudo systemctl daemon-reload
sudo systemctl restart scd-server

Permission denied — the service user does not own the files:

sudo chown -R scd-server:scd-server /opt/scd-server

Server starts but license is not recognised​

Check that the files are in place and owned by the service user:

ls -la /opt/scd-server/data/
# license.key and scd-public.pem should be present, owned by scd-server

If scd-server was started before the license file was placed, restart it:

sudo systemctl restart scd-server