Adding custom 404 pages to sourcehut pages

Tags: meta

As I mentioned in a previous blog post, this site is hosted on (sourcehut’s static hosting service). The default 404 page for static sites is simply the plaintext “404 page not found”, which is not very useful. Other services like Github Pages let you configure a custom 404 page.

It turns out this functionality is also available in sourcehut pages as of this recent patch. Unfortunately, the functionality is only available through sourcehut’s GraphQL API at, which has very little documentation.

Here’s how you can upload your site.tar.gz to a domain, while also having 404 requests serve 404.html:

acurl -F 'operations={"query": "mutation ($site: Upload!)'\
    '{ publish(domain: \"\", content: $site,'\
    'protocol: null,'\
    'subdirectory: null,'\
    'siteConfig: {notFound: \"404.html\"} ) { id } }'\
    '", "variables": {"site": null}}' \
    -F 'map={"0":[""]}' \
    -F 0=@../site.tar.gz

and you can see my (boring) custom 404 page here.

A quick breakdown:

Since my configuration actually updates two sites at once (both and, I tried to do both requests in one GraphQL request. Unfortunately this errored out with EOF, presumably because the upload can only be used once. I ended up just copy-pasting that command twice.

Posted on 2022-03-27