Fantasma
Troubleshooting

Publishing to Ghost failed

On this page

When a publish fails, "Publish failed" appears with the reason under it. The Publish menu, which opens from Publish at the top of the editor's right sidebar, keeps showing the last failure until a publish works. A theme download that fails shows "Download failed" with its reason. Your site keeps the theme it had before, and your project in Fantasma keeps all your edits.

When Ghost or something in front of it refuses the publish, you can often still download the theme and upload it in Ghost yourself while you fix the cause.

Check the basics first

  • The Ghost page of Project settings shows Connected. To open it, click the sliders icon in the icon rail, Project settings, then Ghost. If it shows Needs attention, fix the connection first: Fantasma can't connect to my Ghost site.
  • Your Ghost site opens in a browser, and Ghost Admin works.

Ghost refused the key

"Ghost rejected the Admin API key or Staff access token. Copy it again from Ghost." or "Ghost connection isn't valid. Check your site URL and Admin API key or Staff access token."

The key was regenerated or its integration was deleted in Ghost after you connected. Copy a fresh key in Ghost Admin, or add a new custom integration if you deleted the old one, as Connect your Ghost site shows. Then in Project settings › Ghost, click Replace under Access, paste the key, and click Save and verify.

Something in front of Ghost blocked the upload

"Your Ghost site refused the theme upload (HTTP 403) without a Ghost error message. A CDN, firewall, or security rule in front of /ghost/api/admin/ usually causes this."

Allow requests to /ghost/api/admin/ in your CDN or firewall, or ask your host to, as Fantasma can't connect to my Ghost site describes.

Your server answered with another error

When the message names another number after HTTP, such as 502, the server in front of Ghost had a problem of its own. Wait a few minutes and publish again. If it repeats, send the message to your host.

The theme is too large for your server

"Your Ghost site answered the theme upload with HTTP 413 and no Ghost error message, so something in front of Ghost replied instead of Ghost."

HTTP 413 means the web server in front of Ghost limits the size of an upload, and the theme is bigger. This happens on self-hosted sites. Ask whoever runs the server to raise the limit, such as client_max_body_size in Nginx. Images you uploaded and fonts in the theme make it larger. Delete unused images in the media library, as Add images and photos shows, and remove fonts you do not use in the Manage fonts dialog under Styles › Typography.

Ghost rejected the theme

"Ghost rejected the theme upload:" followed by Ghost's own reason.

Ghost checks every theme before it installs it. The theme needs Ghost 6 or later. If your site runs an older Ghost, update Ghost first, or ask your host to. Your host or Ghost Admin's about screen tells you the version. For any other reason Ghost gives, contact us with the full message.

The upload went through, but activation is unconfirmed

"Theme uploaded, activation unconfirmed"

In Ghost Admin, open Settings, then Design & branding, and click Change theme to see which theme is active. If it is not fantasma- followed by your theme name, such as fantasma-ridgeway-dispatch, activate that theme. The theme name is under Project settings › General. Publishing again replaces the same theme, so no extra copies pile up in Ghost.

The build stopped

These reasons come from Fantasma before anything reaches Ghost. The same reasons stop a download.

Message What to do
"Couldn't build your theme file" Try again in a minute. If it repeats, contact us.
"Project exceeds the 4 MiB size limit. Remove content and try again." The project holds too much text and settings. Remove sections you do not use, or long scripts in Project settings › Custom code. Limits lists the project limits.
"Could not bundle" followed by a font's name The project already holds as many fonts as it can. Remove a font family, or turn off Bundle fonts in theme in the Manage fonts dialog, under Styles › Typography. With it off, your site loads those fonts from Google Fonts and looks the same. See I reached a project, image or font limit.
"Invalid template routing" An address in your templates breaks a rule, and the message does not say which. Check each collection under Collections in the Templates list: two collections cannot share a Path or an Internal tag, and each Post permalink needs {slug}. The Tag and Author templates, in the same list, need different addresses.
"Invalid collection path for", "Invalid collection permalink for" or "Invalid tag taxonomy path" Correct the address the message names. Create a part of your site with its own URL shows the valid forms.

A publish is still running

"A publish is already in progress"

Another publish of this project, from this window or another one, has not finished. Wait a minute, then publish again. After about three minutes, an unfinished publish no longer blocks a new one.

When the reason says "Too many publish attempts.", you published more than 10 times in 5 minutes or 30 times in an hour, failed attempts included. Wait for the number of seconds shown in the message.

Contact support

If the reason is not here, or the fix did not help, contact us and send:

  • the full text under "Publish failed" or "Download failed"
  • the address of your Ghost site, and whether it is on Ghost(Pro) or self-hosted
  • your Ghost version, if you know it
  • the theme version shown in the Publish menu, such as v2.0.0-3
  • a screenshot of the Ghost page in Project settings

Was this article helpful?