Common Issues & Solutions

Here are solutions to the most common issues you may run into when setting up or running Markdesk.

Build fails with missing dependencies

If npm run build fails with module-not-found errors, try a clean install:

rm -rf node_modules
npm install

If you changed emailSender in your config, make sure the corresponding package is installed:

# For Resend
npm install resend

# For SendGrid
npm install @sendgrid/mail

# For Nodemailer
npm install nodemailer

Articles not appearing after adding new files

After creating or editing markdown files, you need to rebuild the search index and content:

npm run build:search
npm run build:content

In development (npm run dev), article pages are generated dynamically, but the search index and beacon content are static and need rebuilding.

Beacon not loading on my site

Make sure the helpCenterUrl in your MarkdeskConfig points to your deployed help center URL (not localhost).
Check that your help center is deployed and beacon.js is accessible at https://your-help-center.com/beacon.js.
If you see CORS errors, add your site's domain to allowedOrigins in markdesk.config.ts.

Contact form not sending emails

Verify your email sender environment variable is set correctly (RESEND_API_KEY, SENDGRID_API_KEY, or SMTP credentials).
Check that emailSender in markdesk.config.ts matches the provider you've configured.
For CORS issues with the beacon contact form, add your site's domain to allowedOrigins.

Search not finding articles

The search index is generated at build time. If you've added or edited articles, rebuild it:

npm run build:search

Search matches against article titles, descriptions, and body text. Make sure your articles have descriptive titles and content.

Beacon update modal keeps showing

The update modal appears for updates with showModal: true that are less than 6 months old. Users can dismiss it, and the dismissal is stored in localStorage. If you're testing and want to reset it, clear markdesk-dismissed-* keys from localStorage.

Still need help?

If none of these solutions work, contact us or open an issue on GitHub.