fr1end1y 🧡🎈

Troubleshooting

Contents

Some things to check/do if you are encountering issues with the starter kit (based on real events 👀).

Ensure you are in the right directory

All the commands given in the documentation are intended to be executed from the solution root directory (the directory containing the README and .sln files) so make sure that's where you are in your terminal.

Ensure dependencies are installed

When creating a new solution, the required NuGet and Node.js packages should be installed automatically (unless the --no-restore flag is passed at the command line).

In case this fails or doesn't happen for some reason, run the following commands in the solution root directory to restore dependencies:

dotnet restore
npm install

Ensure the CMS is running and content is published

Eleventy builds currently fail with an exception if the Umbraco Delivery API cannot be contacted, or if no content is returned (at least homePage and siteSettings nodes must exist and be published).

One issue I have been facing is that sometimes the content imported by uSync FirstBoot is not properly published:

A screenshot of the Home node info in the Umbraco backoffice. Under the Links section is the error: "This document is published but its URL cannot be routed".

If you see the above error on the Home node, then publish it with descendants, including unpublished content items:

The Umbraco "Publish with descendants" modal overlaid on the Home content in the backoffice. The "Include unpublished items" option is enabled.

Rebuild the Umbraco Delivery API index

Another thing worth checking is if all content has been indexed in the Content Delivery API Examine index. In Umbraco, navigate to the Settings section, open the Examine Management dashboard, and select the DeliveryApiContentIndex.

Check to see if the document and field counts in the index look correct:

A screenshot of the DeliveryApiContentIndex in the Umbraco Examine Management dashboard, listing properties of the index such as document and field counts.

Rebuild the index by clicking the Rebuild Index button under Tools:

A screenshot of the Rebuild Index button in the Tools section of the Examine Management dashboard.

Check your logs

Use the Umbraco Log Viewer or Eleventy's DEBUG mode to see if you can get more information about what's going wrong.

Check your configurations

Maybe you have a configuration error somewhere. Head over to the configuration docs for details about the template configuration settings and defaults.

Run cleanup script

This script will run dotnet clean for the CMS project and clear out the Eleventy output and cache directories:

npm run clean

Turn it off and on again

You know the drill. Restart your web browsers, dev servers, terminals, editors/IDEs, your computer... Clear every cache and try again.

Report an issue

If all else fails, create an issue on GitHub and I'll try my best to help 🙂.