Troubleshooting & FAQ

QSCS is built to run quietly for months at a time. The questions below are the ones that come up while you are getting a fresh cluster wired up, almost all of them are configuration nudges rather than anything actually going wrong with the daemon.

A node came up as role=Node and I wanted it to be master

Role is decided by matching the local Tag against the Master entry of the [Domain] block. Two things to check:

1. Make sure there is no stray lowercase tag = … line in [QSCS Daemon] shadowing your Tag. If there is, remove it and restart.
2. Confirm the master designation in the control panel points at the node you intended. Open the cluster page, click ★ on the right node, then re-subscribe.

A thin client returned 503 instead of HEADLESS

HEADLESS serves URLs from the local cache, so it only covers URLs the node has already seen. The very first request for a brand-new URL while the master is unreachable is the one case HEADLESS cannot answer, the response is 503 with X-QSCS-Mode: full. As soon as the master is reachable again the URL is cached and HEADLESS covers it from then on.

I see Implicit upstream resolved to 0.0.0.0:8080 in the log

That just means the thin client has not yet found a peer marked Master in its [Domain] block. Designate the master in the control panel and re-subscribe and the line will disappear.

The cluster works from inside the host but not from the outside

This is a firewall / binding question, not a QSCS one. Confirm:

• Your cloud provider's security group allows TCP 8080 inbound to the master from each thin client's IP.
• The master is binding 0.0.0.0 rather than 127.0.0.1 (see [HTTP Listener].Bind).
• The thin client's [Origins] entries point at the master's public address.

qscs subscribe says “domain not found”

Cluster tags are case-sensitive and must match exactly what is in the control panel. If you have just created the cluster, give the panel a moment to commit before re-running.

The cache appears to start empty on every restart

That is EphemeralMode doing its job. It is a hardening option for secure environments that signs every request with a per-request key and deliberately does not persist cache state to disk between runs. If you want the cache to survive restarts (the normal production setting), leave EphemeralMode at its default false in [QSCS Daemon].

Where is my license key?

Control panel → your account → Licenses. Each license binds one-to-one to a node UUID the first time it is activated.

Can I run QSCS in a container?

Yes, lots of people do. Map the public listener port (default 8080) and the inter-node port (default 4443), bind-mount /etc/qscs/qscs.conf and /opt/qscs (for the identity DB and cache), and run the binary directly. If you want the cache to persist across container restarts, put /opt/qscs on a real volume rather than the overlay.

How big does the cache get?

It is bounded by default to a fraction of host RAM and managed by QSCS itself, you do not have to size it manually. Watch qscs_cache_bytes on the metrics endpoint if you want to see the current footprint.

I have a question that is not on this list

Drop us the relevant journal line (journalctl -u qscs) and your userID to support@spook.systems. Every internal log line is tagged with the source subsystem and a stable identifier, so even short snippets are usually enough to pin down what is happening.