Troubleshooting

`Permission denied` on port 80

Low ports often require privileges.

Use a high port:


qaws --host 127.0.0.1 --port 8080 --serve ./public

Or configure your operating system to allow the binary to bind privileged ports.

Docker container starts but files are missing

Check the mounted directory:


ls -la public
docker run --rm -p 8080:80 -v "$PWD/public:/public:ro" ghcr.io/nulldoubt/qaws:0.2.7

The mounted directory must contain the files you want qaws to serve, such as index.html.

Docker port is unreachable

Make sure the host port is published:


docker ps
curl -i http://127.0.0.1:8080/

If you override --host inside the container, use 0.0.0.0, not 127.0.0.1.

`unexpected e_type: 2` on Termux

You are running a normal Linux binary on Android. Use the Termux artifact:


qaws-0.2.7-aarch64-linux-android

Install it:


install -m 755 ./qaws-0.2.7-aarch64-linux-android "$PREFIX/bin/qaws"

`qaws help` or `qaws version` behaves oddly on Termux

Use a current qaws Termux build. qaws includes a Linux /proc/self/cmdline argv workaround for duplicated argv0 forms observed on static Termux startup.

Cloudflare Tunnel feels slow

Measure qaws directly before judging the tunnel path:


curl -o /dev/null -s -w 'time_total=%{time_total} size=%{size_download}\n' http://127.0.0.1:18086/

Then compare the tunnel URL. Quick tunnels add extra network hops, and phone CPU scheduling can dominate perceived speed.

Daemon starts but the site is unreachable

Check:

the serve directory exists
the selected port is not already in use
the daemon log file
the bind host

Example:


qaws -d --pid-file /tmp/qaws.pid --log-file /tmp/qaws.log --port 18086
qaws status --pid-file /tmp/qaws.pid
tail -n 100 /tmp/qaws.log

Daemon already running

Use the same daemon identity to inspect or stop it:


qaws status --pid-file /tmp/qaws.pid
qaws stop --pid-file /tmp/qaws.pid

If you did not set --pid-file, pass the same host and port used at startup:


qaws status --host 127.0.0.1 --port 18086

`qaws check` fails

qaws check validates both the config and serve directory.

Common causes:

unknown JSON keys
invalid JSON types
zero tuning values
missing serve directory
custom headers that try to override protected runtime headers

Run:


qaws check --config qaws.json

Fix the first reported error, then rerun.

A changed cached file is briefly stale

The default cache revalidation interval is 1000 ms. After the interval, qaws stats the file and reloads it only if size or nanosecond mtime changed. Wait for the interval, preserve accurate filesystem mtimes when deploying, or reduce cache.revalidate_ms in JSON.

A precompressed sidecar is not selected

Confirm all three conditions:

http.precompressed is enabled
the sidecar is adjacent to the identity file, such as app.js.br
the request’s Accept-Encoding gives that encoding a positive quality

Inspect negotiation directly:


curl -I -H 'Accept-Encoding: br, gzip' http://127.0.0.1:8080/app.js

An encoded response includes Content-Encoding and Vary: Accept-Encoding. A direct request for /app.js.br is treated as an ordinary file and does not infer Content-Encoding.

A range request returns 200

qaws supports one byte range. A valid multipart set such as bytes=0-9,20-29 is intentionally ignored and returns the full 200 representation. Use one normal, open-ended, or suffix range and confirm http.range_requests is enabled.