Troubleshooting

Find solutions for common setup, upload, routing, and theme configuration issues that can appear while installing or updating your Ghost theme.

Use the same ZIP filename for each update, for example theme-name.zip. This helps Ghost keep the existing Design & branding settings for that theme.

Ghost stores Design & branding settings by uploaded archive name. If you upload theme-v1.zip and later theme-v2.zip, Ghost treats them as separate themes and the settings will not carry over.

This applies only when updating the same theme. Different themes can have different custom settings.

This usually means a previous theme used a custom routes.yaml file. Reset routes.yaml to the default Ghost routes to resolve it.

routes:
collections:
  /:
    permalink: /{slug}/
    template: index
taxonomies:
  tag: /tag/{slug}/
  author: /author/{slug}/

1. Go to the 'Labs' settings in the Ghost Admin to find the 'Routes' section.
2. Upload the routes.yaml file with these settings:

routes:
collections:
  /:
    permalink: /{slug}/
    filter: featured:false
    template: index
  /featured/:
    permalink: /featured/{slug}/
    filter: featured:true
    template: index
taxonomies:
  tag: /tag/{slug}/
  author: /author/{slug}/