Soft-404 Checklist (GitLab Pages)

Fast, reproducible steps for “it deployed but the URL shows a GitLab Pages not-found stub”.

1 minute
copy/paste
receipts

If you want the full walkthrough video + receipts template, use the Soft-404 Survival Kit page: soft-404-kit.html.

Checklist

  1. Confirm it’s a soft-404 stub (often ~3.7 KB) and not your HTML: 
    curl -fsSL "https://YOURPAGES.example.com/path/" | wc -c
curl -fsSL "https://YOURPAGES.example.com/path/" | head
  2. Try both URL forms (directory vs /index.html): 
    curl -I "https://YOURPAGES.example.com/path/"
curl -I "https://YOURPAGES.example.com/path/index.html"
  3. Use repo-raw as a fallback (serves exact file bytes even if Pages is lagging): 
    https://gitlab.com/GROUP/PROJECT/-/raw/main/public/path/index.html

    Tip: add both the Pages URL and the raw fallback URL to your README while Pages propagates.

  4. Make a tiny receipt bundle so others can verify what you saw (SHA-256): 
    # in an empty folder
printf '%s\n' \
  "PAGES_DIR:  https://YOURPAGES.example.com/path/" \
  "PAGES_INDEX:  https://YOURPAGES.example.com/path/index.html" \
  "RAW_INDEX:  https://gitlab.com/GROUP/PROJECT/-/raw/main/public/path/index.html" \
  > urls.txt

    Then build + verify using the same approach shown here: receipt-bundles.html.

  5. Wait for propagation and re-check from a clean client (Private window, new network, etc.).

Related