Troubleshooting

Starting the server#

unable to set up TCP listener: Permission denied (os error 13)#

Ports below 1024 need privileges. Use a higher port (--port=7878), or run with sudo / as Administrator. In a container, the release image runs as a non-root user, so map a high container port to 80/443 instead.

unable to set up TCP listener: Address already in use#

Another process holds the port. Find it:

sudo lsof -i :7878     # macOS and Linux
sudo fuser 7878/tcp    # Linux

Cannot assign requested address (os error 99)#

The --ip you passed isn't assigned to any local interface. List them with ip addr (Linux) or ifconfig, or bind to all of them with --ip=0.0.0.0.

sudo rws says command not found#

~/.cargo/bin (or /usr/local/bin) isn't on root's PATH. Use the full path: sudo ~/.cargo/bin/rws.

Reaching the server#

Other machines can't connect#

• Bound to 127.0.0.1? That only accepts local connections. The default is 0.0.0.0; pass --ip=0.0.0.0 if you overrode it.
• Connection refused from another host with the right IP: a firewall is blocking the port.

Serving on IPv6#

rws --ip=:: listens on IPv6 (and IPv4-mapped addresses). Link-local fe80::… addresses need a zone id that browsers rarely accept; connect with the machine's IPv4 address or a global IPv6 address instead.

HTTPS, HTTP/2 or HTTP/3 isn't working#

No certificate is configured, so rws falls back to plain HTTP/1.1. Provide one (HTTPS / TLS) or let rws get one (ACME):

rws --tls-cert-file=/path/to/cert.pem --tls-key-file=/path/to/key.pem

TLS setup failed: failed to read cert file …#

The path is wrong, the process can't read it, or the file isn't PEM. Both the certificate (chain) and the key must be PEM.

The browser warns about the certificate#

Self-signed certificates aren't trusted. For local development add yours to the system trust store (or use mkcert); in production use a public CA, for example through ACME.

Malformed-request errors (400)#

The server received something that isn't an HTTP request — a port scanner, TLS sent to a plain-HTTP port, or garbage. The client gets a 400 Bad Request; it's safe to ignore.

A directory shows a file listing#

A directory without index.html is shown as a listing. Add an index.html to serve that instead.

Logs and metrics#

I want the Combined Log Format, not JSON#

Set RWS_CONFIG_LOG_FORMAT=combined (or log_format = "combined" in rws.config.toml); off disables the access log. JSON is the default. Lines are buffered and written within 100 ms — see Observability.

Scraping metrics#

GET /metrics serves Prometheus text format; see Metrics for the metric names and a scrape config.

Kubernetes#

Probes fail with Connection refused#

The kubelet probes the pod IP, so rws must not be bound to 127.0.0.1. The default 0.0.0.0 works; check for an ip = "127.0.0.1" override.

/readyz returns 503 right after start#

Expected: it returns 503 until startup finishes, then 200. If it stays at 503, startup failed — check the logs. Give slow starts an initialDelaySeconds:

readinessProbe:
  httpGet:
    path: /readyz
    port: 7878
  initialDelaySeconds: 5
  periodSeconds: 5

Requests are dropped on SIGTERM#

rws stops accepting on SIGTERM and finishes in-flight requests. Requests can still arrive while the load balancer hasn't noticed yet; delay termination with a preStop sleep (Kubernetes 1.30+ — the release image has no shell for an exec hook):

lifecycle:
  preStop:
    sleep:
      seconds: 5

More in Kubernetes.

Building from source#

linker 'cc' not found#

Install a C toolchain (needed by aws-lc-rs and other native dependencies):

sudo apt-get install build-essential        # Debian/Ubuntu
sudo dnf group install "Development Tools"  # Fedora/RHEL
sudo pacman -S base-devel                   # Arch

found crate … compiled by an incompatible version of rustc#

Stale build artifacts from another toolchain: cargo clean && cargo build.

error: package … requires rustc 1.88#

The minimum supported Rust version is 1.88: rustup update stable.

failed open - '…/FETCH_HEAD' is locked: Permission denied#

The Cargo registry was written by sudo cargo … once. Fix the ownership (sudo chown -R $USER ~/.cargo) rather than building as root.