Troubleshooting

Having issues with your theme? Here are solutions to the most common problems.

Installation Issues#

Theme won't upload or shows errors#

1. Check the Ghost version. Break needs Ghost 6.39 or newer, because it uses template helpers older versions do not have. Update Ghost first.
2. Verify the ZIP file. Upload the original break.zip file, not a folder or extracted files.
3. Check the file size. Ghost has a limit on upload sizes. On Ghost(Pro) it is typically 50MB.
4. Clear the browser cache. Try a hard refresh (Ctrl+Shift+R or Cmd+Shift+R).

A page returns a 404#

The /blog/, /projects/, /newsletters/, /issues/ and /bookmarks/ pages come from the routes.yaml file that ships with the theme. Upload it in Settings → Advanced → Labs, as described in Getting Started. Until it is uploaded, posts tagged #newsletter also stay on the front page.

The Your account button on the sign-in page leads to /account/, which only exists once you create a page with that URL. See Account and Sign-in.

A special page looks like an ordinary page#

Pages such as Live, Video, Podcast, Markets, Archive, Tags, Authors and Membership are picked by their Page URL. It has to be exactly live, video, podcast, markets, archive, tags, authors, recommendations, membership, account, signin or subscribe. A page with the URL videos or our-authors is shown as an ordinary page.

The text I wrote on a page does not show#

The Live, Video, Podcast, Markets, Archive, Tags, Authors and Recommendations pages show only their title, their excerpt and their list. Anything written in the page body is not shown there. The Membership, Account, Sign-in and Subscribe pages do show the page body, below their own content.

The title and excerpt of the list pages only appear when Show title and feature image is enabled in Page settings.

Front Page Issues#

A section is missing from the front page#

A section without content renders nothing, and the section numbers skip it. Most sections need a tag or a page to exist first, for example a public tag with the slug opinion for the Opinion section, or posts tagged #audio for Listen. See Overview for what each section needs.

There is no setting to turn the featured post on#

The front page always opens with the featured post. It shows the newest post marked Featured in Post settings, or the latest post when none is featured. The Homepage cover setting only changes its look. See Featured.

The front page scrolls sideways#

On a landscape desktop screen, every page of the site reads sideways except posts and ordinary pages, which always read top to bottom. Readers can switch the whole site to vertical with Scroll in the settings panel or the r key. To make every page vertical for everyone, add reading-columns to Disabled features. See Reading Mode.

Posts are missing from the front page#

1. Check the post status. Make sure the posts are published, not drafts.
2. Check for #newsletter. Posts with that tag leave the front page feed and /blog/ on purpose. See Newsletters.
3. Clear the cache. Try clearing your browser cache.

The live page does not update#

The Live page checks for new posts every 60 seconds, and only while it is open in a visible browser tab. If auto-refresh is listed in Disabled features, it does not check at all. See Live, Video and Podcast.

Navigation Issues#

Menu not showing#

1. Go to Settings → Navigation
2. Add menu items with labels and URLs
3. Click Save
4. Refresh your site

Dropdown menus not working#

Break builds dropdowns from the primary navigation alone. An item whose label starts with - becomes a row in the dropdown of the regular item above it. Secondary navigation items do not make dropdowns. See Navigation.

A mega block shows as a plain link#

Rows whose label starts with @ open a block of posts, tags, authors, projects, recommended sites or a subscribe form in the top bar. In the menu panel they are plain links on purpose. They also fall back to plain links when Ghost runs in a subdirectory, such as example.com/news/, because the block is picked from the start of the row's URL.

Styling Issues#

The site switches to dark although I chose Light#

While readers have the light and dark choice in the settings panel, the Dark mode setting is only the scheme a first-time visitor starts with. Until a visitor picks a scheme, the site can follow a change of their system's scheme. To fix the scheme for everyone, set Dark mode to Light or Dark and add toggle-dark-mode to Disabled features. See Dark Mode.

Ads do not show#

The two ad slots are listed in Disabled features by default, as header-ad and in-article-ad. Remove the keyword of each slot you want, then fill in Adsense publisher id and the slot's own id. Paid members never see ads. See Ads.

Layout looks different than the demo#

1. Check the theme settings. Go through all options in Design → Customize → Theme.
2. Verify routes.yaml. Several pages only exist with it.
3. Review the content. Many sections of the demo come from tags and pages with specific slugs.

Images not displaying#

1. Check the image format. Use standard formats (JPG, PNG, WebP, GIF).
2. Verify the image size. Very large images may fail to load.
3. Check the image URLs. Make sure images are properly uploaded to Ghost.
4. Clear the CDN cache. If you use a CDN, clear its cache.

Member Issues#

Subscription form not showing#

The subscribe form only appears when members are turned on in ⛭ Settings → Membership, and never for a reader who is already a member. Sign out, or open the site in a private window, to see it the way a visitor does.

Bookmarks disappeared#

Bookmarks live in the reader's browser, not on your site. Clearing browsing data, switching browsers or devices, or a private window starts the list over. See Bookmarks.

Messages in the Server Log#

If you run Ghost yourself, its log can show NotFound errors for the slugs numbers, agenda, house-ad, opinion, picks, longreads and markets. The front page looks for a page or a tag with each of these slugs, and Ghost logs the lookup when it does not exist. This is expected and harmless. Create the page or tag to use that section, or ignore the message.

Ghost also adds "(Page 1)" to the browser title of the first page of /blog/, /projects/ and /newsletters/ once they have more than one page. This comes from Ghost, not from the theme.

Still Having Issues?#

If you've tried these solutions and still have problems:

1. Check the FAQ for more answers
2. Review the complete documentation
3. Contact our support team with:
   • Your Ghost version
   • Theme version
   • A description of the issue
   • Screenshots if applicable
   • Any error messages you're seeing