When a site says Failed

Hosting is built, and a few accounts are using it first. It opens to everyone once the rules, a way to report a site and a way for us to take one down are ready.

A site that did not publish reads Failed in the Hosting tab of your console, with the reason under its name. Each reason below is quoted as the product writes it; the console prints it with a capital letter at the start and a full stop at the end.

A deploy that fails does not take a site down. If the site was already serving a version, that version keeps being served while the card reads Failed, so you can fix the repository and press Redeploy without the address going offline in between.

Pressing Redeploy uses one of the day’s deploys whether the publish succeeds or fails, so it is worth checking the folder before you press it rather than after. Plans and limits has the number each plan allows.

There is no index.html in the folder you published

there is no index.html at the top of the folder dist, so the address would show "not found". The top of the repository has one. Leave the folder empty

A site is published only with a front page, because / is served from /index.html. Rather than put an address online that answers “not found”, we refuse the publish.

The sentences after the first one are the useful part: while we read your repository we note every folder that holds an index.html directly, and the message names them. A line reading Leave the folder empty means the field should be empty; a list like Folders with an index.html: site, docs names the folder to put in it instead.

If there is none anywhere, the message says that instead:

this repository has no index.html anywhere, and a site needs one as its front page

Then the file is missing rather than misplaced. Add an index.html, commit it, and press Redeploy.

The folder does not exist on that branch

there is no folder called dist on branch main. Folders with an index.html: site

The folder is a path inside your repository, and it is looked for on the branch you named. A folder your tooling builds but nobody commits does not exist on the branch, however plainly it exists on your computer. The message ends with the folders that do have a front page, so it usually names the one you meant.

A folder written in a shape we cannot use is refused with a different sentence:

the folder must be a plain path inside the repository, like dist or site/public

That is a plain relative path: no leading slash, no .., no drive letter.

The repository is not public

your-name/your-repo (branch main) was not found on GitHub, or is not public — hosting takes public repositories only

We read your repository the way anyone else does, without signing in, so a private repository and a repository that does not exist look exactly the same from here. The same sentence covers a misspelled name and a branch that is not there. It is checked before the site is created, so nothing is charged.

A repository that was renamed says so on its own:

your-name/your-repo has moved on GitHub; use its current name

A file is too large

assets/intro.mp4 is 40 MiB; a single file may be at most 25 MiB

The number at the end is the limit (a MiB is a unit close to a megabyte); the number in the middle is your file. A video or an archive committed next to the pages is the usual cause. Make the file smaller, or keep it somewhere built for large files and link to it.

Too many files, or too much altogether

more than 10000 files; the repository path publishes at most that many

the folder is larger than 50 MiB, the most the repository path can publish

Both are limits of publishing straight from a repository: everything a site weighs is held in memory between the download from GitHub and the upload, so the whole folder has to fit. Publish a narrower folder — the built output rather than the whole project — and check that nothing unrelated is committed inside it.

An empty folder is refused as well, with:

the folder dist has no files

A link instead of a file

assets/logo.svg is a link; links are not published, copy the file instead

Symbolic links and hard links — shortcuts that point at another file — are refused rather than followed: what a link points at is decided on the machine that made it, not in the repository. Commit the real file in its place.

A file name the platform keeps

A few names at the top of a published folder belong to the serving platform rather than to your site. If your folder has one of them, the publish is refused with a sentence that names the file and ends:

at the root is reserved and cannot be published

Rename the file, or move it one folder down.

The day’s deploys are used up

3 deploys a day on the Free plan; try again tomorrow or move up a plan

Every plan allows a number of deploys a day, and Redeploy and Change folder both count as one. The number in the message is your plan’s; they are listed in Plans and limits.

This refusal is the one that costs nothing: it is turned down before the publish starts, so it does not use a deploy, and it appears as a note above your sites rather than on a card. A publish that starts and then reads Failed has already used one.

What else the console says

Two more refusals happen when a site is created rather than when it is published, so they appear in the form and not on a card:

Not enough balance for the first month. Top up and try again.

you already have your free site; choose a paid plan, or delete the other site first

The first means the wallet cannot cover the plan’s first period; the second is the one free site an account may hold.