Troubleshooting

If a problem began while updating a 3.x blog, complete Upgrade to 4.0 before isolating individual modules.

Build and configuration

1. Run hexo clean and regenerate.
2. Validate YAML indentation in both configuration files.
3. Compare top-level theme keys with the v4.0.0 default configuration.
4. Disable only the most recently enabled module and reproduce the error.

ES modules and CDN

• Confirm that main.js is loaded with type="module".
• Inspect the first failed dynamic import in the browser network panel.
• Ensure every first-party file comes from the same Solitude version.
• Preserve the complete relative source/js/ directory tree on a custom CDN.
• Do not rewrite module URLs to isolated flattened filenames.

PJAX accumulation

Navigate repeatedly between the same two pages. Duplicate dialogs, players, callbacks, or network requests usually indicate custom code that registers permanent resources on every afterNavigate. Subscribe once, then use the page-scoped cleanup methods in Browser API.

Data and integration checks

• Confirm YAML data is an array or object matching the feature guide, not a generic items wrapper.
• Verify /links.json when friend-link asynchronous mode is active.
• Verify /search.xml before debugging the local search UI.
• Test provider URLs and domain allowlists from the deployed origin.
• Check that only supported providers are used for recent comments and PV counts.

When reporting a problem, include the Solitude version, Hexo and Node versions, relevant configuration with secrets removed, the generated URL, and the first console or network error.