---
title: Troubleshooting & Diagnostic Error Matrix
description: Common issues, diagnostic steps, error codes, and practical resolutions for VertiWiki deployments.
tags: [vertiwiki, troubleshooting, diagnostics, errors, debugging, faq]
---

# Troubleshooting & Diagnostic Error Matrix

> For the complete documentation index and agent navigation, see [llms.txt](/llms.txt).

This guide provides an exhaustive diagnostic matrix for identifying and resolving operational, configuration, and rendering issues in VertiWiki.

---

## 🔍 Diagnostic Error Matrix

| Symptom / Error | Root Cause | Immediate Resolution |
| :--- | :--- | :--- |
| **`Access to fetch at 'file://...' from origin 'null' has been blocked by CORS policy`** | Opening `index.html` directly from the local filesystem via double-click. Modern browsers restrict `fetch()` on `file:///`. | Launch an HTTP server: `python3 -m http.server` or `npx serve .`. |
| **Blank white page on initial load** | Syntax error in `config.json` (trailing comma, unescaped quote). | Run `jq . config.json` or paste content into a JSON validator. Fix syntax and refresh. |
| **404 Not Found when clicking sidebar link** | Target Markdown file does not exist at the exact case-sensitive path specified in `navigation.md`. | Confirm that the `.md` file path matches `navigation.md` character-for-character, including casing. |
| **Mermaid diagram renders raw text instead of SVG** | Diagram block missing language tag, syntax error inside mermaid block, or unclosed fence. | Ensure code block begins with ```` ```mermaid ```` and uses valid Mermaid syntax (e.g. `graph TD`). |
| **LaTeX math formula displays raw dollar signs `$..$`** | `enableMath` is set to `false` in `config.json` or syntax contains unescaped characters. | Verify `"enableMath": true` in `config.json`. Use `$$...$$` for block math or `\(...\)` for inline math. |
| **Search modal (<kbd>⌘K</kbd>) finds no results** | Documents have not finished background indexing, or query contains language mismatch. | Check console for MiniSearch initialization errors. Note that search scopes to active locale (`en`, `ro`, `fr`). |
| **Double-prefix in URL (`/#/ro/ro/guide.md`)** | Relative links in localized files explicitly prepended locale prefix. | In localized navigation files (`ro/navigation.md`), use clean relative links (`guide.md` or `concepts/arch.md`), not `ro/guide.md`. |
| **FOUC (Flash of Unstyled Content)** | Slow network or missing critical skeleton shell in custom HTML distributions. | Ensure `.verti-loading-shell` is intact in `index.html` before JavaScript initialization. |

---

## 🛠️ Step-by-Step Diagnostic Procedures

### 1. Verifying Network Fetch Status
1. Open Developer Tools (<kbd>F12</kbd> or <kbd>Cmd+Option+I</kbd>).
2. Switch to the **Network** tab.
3. Reload the page and filter by **Fetch/XHR**.
4. Inspect HTTP status codes:
   - `config.json`: Must return `200 OK`.
   - `navigation.md`: Must return `200 OK`.
   - Target `.md`: Must return `200 OK`.
5. If any request returns `404 Not Found`, inspect the **Request URL** to verify base directory resolution.

### 2. Validating YAML Frontmatter
VertiWiki parses YAML frontmatter delimited by `---` lines at the very beginning of the document (line 1). If frontmatter fails to parse:
- Ensure there are no spaces or blank lines before the first `---`.
- Check that string values with colons or special characters are quoted (e.g. `title: "My Title: Part 1"`).
- Tags must be a valid array (e.g. `tags: [one, two]` or list format).

---

## 💬 Getting Further Help

If your issue is not resolved by the diagnostic matrix above:
- Search existing discussions on the [GitHub Repository](https://github.com/Octadira/vertiwiki/issues).
- Inspect the [Interactive Visual Sitemap](../sitemap.md) to ensure correct document hierarchy.
- Review configuration options in [Configuration Overview](../configuration/overview.md).