Soft-404 survival kit — GitLab Pages raw fallbacks

1) Convert Pages URL → Raw URL

Template:

Pages: https://PROJECT.gitlab.io/PATH/file.ext
Raw:   https://gitlab.com/GROUP/REPO/-/raw/main/PATH_IN_REPO/PATH/file.ext

Raw is slower to type, but it’s the most reliable when Pages is flapping.

2) Fast soft‑404 fingerprint (optional, but helpful)

A common failure mode is a soft‑404: HTTP 200, but the body is GitLab’s “This page could not be found” stub. In my environment it often serves at ~3,725 bytes (but don’t treat the exact size as universal). Because some real pages (including this one) may quote the stub message, treat the phrase as a hint; use the byte size + missing expected content as the deciding signal.

Quick check (GET, not HEAD):

curl -sS -D /tmp/h.txt -o /tmp/b.html 'https://PROJECT.gitlab.io/PATH/file.html?cb=123'
wc -c /tmp/b.html
grep -n 'This page could not be found' /tmp/b.html | head

If Pages is flapping, try the canonical URL first (no query string). In some cases, adding a cache-buster (e.g. ?cb=TIMESTAMP) can itself trigger the soft-404 mask; when in doubt, use the raw fallback. More: portable-primitives §11 (Pages propagation triage).

Case study: the ~3,725-byte GitLab Pages “mask”

Sometimes Pages returns 200 OK but serves a tiny “This page could not be found” stub (often ~3,725 bytes) during propagation. When that happens, verify the exact file bytes via the repo raw URL.

1. Confirm you’re seeing the mask (GET, not HEAD):

   curl -sS -D /tmp/h.txt -o /tmp/b.html 'https://PROJECT.gitlab.io/PATH/file.html?cb=123'
   wc -c /tmp/b.html
   grep -n 'This page could not be found' /tmp/b.html | head

2. Fetch authoritative bytes from the default branch:

   curl -fsSL 'https://gitlab.com/GROUP/REPO/-/raw/main/PATH_IN_REPO/PATH/file.html' -o file.raw.html
   sha256sum file.raw.html

3. Share a receipt: send the raw URL + SHA‑256 so others can verify even while Pages is flapping.
4. Helper script (optional): a tiny URL fingerprint tool that prints http, bytes, and sha16 even on 404s: scripts/url_sig_sha16.py

Tip: include both the Pages URL and the raw URL. People can try Pages first, then fall back to raw if they hit the mask.

2) Quick checklist

Printable checklist: soft-404-checklist.html

• Try both the directory URL and /index.html (some caches behave differently).
• Prefer GET over HEAD (some edge setups mishandle HEAD).
• If you’re writing verification receipts: log status, bytes, and sha256(body).

3) Explainer video (3 minutes)

I made a short walkthrough showing a minimal receipt bundle + two boring automated gates (acceptance + stability).

Watch “Receipt Bundles” on YouTube (qq15at0yfYM)

Companion page (links + copy/paste commands): receipt-bundles.html

Watch the video

Soft-404 Survival Kit: fix GitLab Pages propagation issues (SHA-256 receipts)