> Markdown version of [Troubleshooting](https://vaadin.com/docs/v23/tools/dspublisher/troubleshooting). Section index: [llms.txt](https://vaadin.com/docs/v23/tools/llms.txt)

# Troubleshooting

<!-- vale Vaadin.HeadingCase = NO -->

This page describes issues you might encounter while using Design System Publisher.

## <a id="cache"></a>The browser doesn’t match the content in the filesystem

To speed up the start process, the Design System Publisher caches some resources internally. Sometimes, caches tend to get out of sync, and need cleaning up. Run `npm run dspublisher:clean` to wipe out the internal caches and restart to see if it fixes the issue.

The issue may also concern the browser’s cache. In case the above doesn’t help, try cleaning the browser’s cache as well.

## <a id="page-heading"></a>Updating the page heading in AsciiDoc doesn’t affect the rendered page heading

There’s one caveat about the page headings. On a regular page, if you change the main heading in the AsciiDoc (`= Page Heading`), you see the heading update as expected. But if you use `layout: tabbed-page` in the page front matter, the tabbed page heading is actually retrieved from the front matter’s title field so you need to update that instead.

## <a id="linux-dependencies"></a>On Linux, the application refuses to start up

Make sure that the necessary dependencies are installed by running the following command:

```terminal
sudo apt install build-essential autoconf automake libtool pkg-config libpng-dev nasm zlib1g-dev
```

## <a id="startup-failure"></a>The development server fails to start up

The `npm run dspublisher:start` script, which starts up the development server, has certain expectations about your development environment. The development server may fail to start up for one of the following reasons.

### <a id="npm-ignore-scriptstrue"></a>npm ignore-scripts=true

If you configure npm with `ignore-scripts=true`, the startup will fail. An example error message for this case is the following:

```
Error in "/Users/[username]/.npm/_npx/c089b35bd0e8ac07/node_modules/@vaadin/dspublish
er/node_modules/gatsby-transformer-sharp/gatsby-node.js":
Something went wrong installing the "sharp" module

Cannot find module '../build/Release/sharp-darwin-arm64v8.node'
```

Remove the `ignore-scripts=true` configuration and delete the `/.npm/_npx` from the home directory to fix the issue.

### <a id="missing-xcode-command-line-tools-macos-only"></a>Missing Xcode Command Line Tools (macOS only)

On macOS, you need [install the Xcode Command Line Tools](https://www.freecodecamp.org/news/install-xcode-command-line-tools/). Otherwise you might receive the following type of error during start up:

```
dsp@[version]:start ████████████████████ Initializing
npx,concurrently,--kill-others,--raw,"npx @vaadin/dspublisher@[version] --develop","mvn -C" failed with code 1
```

`82E98556-B62A-467D-947F-94C586E8A463`
