← Docs hub

Troubleshooting

Common errors and how to fix them.

"No sessions found"

Cause: The agent you expect is either not installed or stores sessions in a non-default location.

Fix:

1. Run python3 -m llmwiki adapters to see which agents are detected.
2. If the agent shows available: no, verify the session store path exists: - Claude Code: ~/.claude/projects/ - Codex CLI: ~/.codex/sessions/ - Copilot Chat: VS Code workspaceStorage/*/chatSessions/ - Copilot CLI: ~/.copilot/session-state/ - Cursor: Cursor IDE workspaceStorage/ - Gemini CLI: ~/.gemini/
3. If the agent stores sessions in a custom location, override it in config.json:

{
  "adapters": {
    "claude_code": {
      "roots": ["/custom/path/to/projects"]
    }
  }
}

4. If you have sessions but they are very recent (< 60 minutes old), the converter skips them as "live sessions." Use --include-current to override:

python3 -m llmwiki sync --include-current

"UnicodeDecodeError" during sync

Cause: Corrupt or binary content in a .jsonl file.

Fix: This was fixed in v0.5 -- the converter now uses errors="replace" when reading files. Upgrade to the latest version:

git pull origin master
pip install -e .

If you still see this error, the file may be severely corrupted. Identify it with --dry-run and exclude it via .llmwikiignore.

Build fails with import error

Cause: The llmwiki package is not installed in your Python environment.

Fix:

pip install -e .
# or, if you don't want an editable install:
pip install markdown

The setup.sh script does this automatically. If you skipped setup, install manually.

Site is blank after build

Cause: No session data exists under raw/sessions/.

Fix:

1. Run llmwiki sync first to convert agent sessions into markdown.
2. Then run llmwiki build.
3. Check that raw/sessions/ contains .md files:

find raw/sessions -name "*.md" | head -5

If empty, see "No sessions found" above.

Code blocks not highlighted

Cause: highlight.min.js or its theme stylesheet is missing from site/.

Fix: re-run llmwiki build. Every build copies highlight.min.js, github.min.css and github-dark.min.css into the output next to style.css; nothing is fetched from the network. If they are still absent after a rebuild, the installed package is missing its vendored assets — reinstall llmwiki.

Heatmap shows no data

Cause: The 365-day activity heatmap requires sessions with valid date information in their YAML frontmatter.

Fix:

1. Verify your sessions have started: or date: fields in their frontmatter:

head -10 raw/sessions/*/2026-*.md

2. If dates are missing, the converter may have failed to extract timestamps. Re-sync with --force:

python3 -m llmwiki sync --force

3. Rebuild the site after re-syncing:

python3 -m llmwiki build

Search returns nothing

Cause: The search index (site/search-index.json) is stale or was not generated.

Fix: Rebuild the site. The build step regenerates the search index from all current content.

python3 -m llmwiki build

If the search index file exists but search still fails, open the browser console (F12) and check for JavaScript errors.

Token/tool charts not rendering

Cause: The visualization components require session frontmatter with total_tokens, tools_used, or similar metadata fields.

Fix: These fields are populated during llmwiki sync. If you have older sessions that predate the metadata extraction, re-sync with --force:

python3 -m llmwiki sync --force
python3 -m llmwiki build

.llmwikiignore patterns not working

Cause: The ignore file uses gitignore-style glob patterns, not regexes.

Fix: Verify pattern syntax:

# Correct: glob patterns
confidential-client/*
*2025-11-*

# Wrong: regex patterns (these will not match)
^confidential.*$

The ignore file must be at the repo root as .llmwikiignore.

Sync is slow

Cause: Re-converting all sessions on every run.

Fix: The converter tracks state in llmwiki-state.json (at the vault root when vault.default_path / --vault is set). If this file is missing or corrupted, it reconverts everything. Normal behavior is to skip unchanged files (fast no-op). If you used --force, the next run without --force will be fast again.

For large session stores (1000+ sessions), the initial sync can take a few minutes. Subsequent syncs only process new or modified files.

Build output is too large

Cause: Very large session stores produce many HTML pages.

Fix:

1. Use .llmwikiignore to exclude projects or date ranges you don't need.
2. Check the perf budget with llmwiki manifest --fail-on-violations.
3. The truncation settings in config.json control how much of each session is rendered:

{
  "truncation": {
    "tool_result_chars": 500,
    "bash_stdout_lines": 5,
    "user_prompt_chars": 4000,
    "assistant_text_chars": 8000
  }
}

Reduce these values to shrink output.