Skip to content

Troubleshooting

Jump to bottom
David edited this page May 31, 2026 · 1 revision

Troubleshooting

When something looks wrong, this page tries to save you a debug session.

Sheet / Gaps panels always empty (fixed in 1.3.1)

Symptom: Cards tab populates, but Sheet and Gaps show "No tagged spans yet" / "No questions or notes yet" even though the note has tagged spans.

Cause (≤ 1.3.0): The view looked up the active file via getActiveViewOfType(MarkdownView), which returns null when the side panel itself becomes the focused leaf. Clicking the Sheet or Gaps tab focused the panel → next refresh wiped paragraphs.

Fix: upgrade to 1.3.1+ — the view now uses workspace.getActiveFile(), which tracks the last active file across leaf switches.

Tag counts empty right after launch

Symptom: Cmd-P → Study: show due-card count shows 0 cards, or sr.api.queries.tagCounts() returns {} immediately after Obsidian loads.

Cause: the vault indexer initializes on workspace.onLayoutReady, which fires a few seconds after plugin load. If you query before that, you see an empty index.

Workaround: wait a moment, or subscribe to changes — sr.api.onIndexChange(cb) fires as soon as the first scan completes.

Custom or domain tag doesn't show in the tagbar

Check:

  1. Mode filter — your tag's inModes field. By default custom tags appear in all five modes; if you set e.g. [5], only Regenerative mode surfaces it.
  2. Domain merge mode — if the active note has semantic_domain: pointing at a profile in replace or subset mode, vault-wide custom tags don't apply.
  3. Sigil validity — must start with a letter, 1–12 alphanumerics, not shadowing a built-in.
  4. Key conflict — built-in key bindings always win. Pick a different letter.

AI commands say "Configure your Anthropic API key first"

You enabled AI features but the key is empty or whitespace. Settings → AI co-reader → Anthropic API key. The key is stored in data.json (plugin folder), never in the vault.

MCP server won't start

Check the developer console (Cmd-Opt-I). Common causes:

  • Port in use — another process on 127.0.0.1:8745. Change the port in settings, or lsof -nP -iTCP:8745 -sTCP:LISTEN to find the conflict.
  • Mobile platform — MCP is desktop-only. The toggle is a no-op on iOS/Android.
  • Token mismatch — if you set a bearer token, every client must send Authorization: Bearer <token>. The Copy config button generates a snippet with the right header.

Verify with Cmd-P → MCP server: show status.

Todoist sync silently does nothing

  • Provider not selected: Settings → Tasks app push → Provider dropdown.
  • Token wrong scope or revoked. Generate a fresh token in Todoist's developer settings.
  • All actions already synced: check the skipped count in the notice. Dedup uses srid_<block-id>_<note-path> labels — go to Todoist and look for these.

ICS subscription shows no events / stale events

  • Calendar app caches subscribed .ics files heavily. Force a refresh or wait an hour.
  • The file path is configurable (Settings → Calendar). If you renamed/moved it, update your subscription URL.
  • Events only emit when an A and a D are in the same paragraph and the D text is parseable as YYYY-MM-DD or YYYY-MM-DDTHH:MM.

Mermaid graph empty after running the command

The note has no R-tagged spans whose text contains an arrow keyword (causes, supports, depends on, blocks, requires, implies, entails, contradicts, leads to, precedes, plus reverse forms). Either:

  1. Add R-tag spans like {{R|attention drives cognition}} (keyword: drives is not in the default set — use causes/supports/depends on/etc.), or
  2. Add your own keyword to the default map in src/integrations/relation-graph.ts (custom mapping in settings is on the roadmap).

If the note has R-tags but they're all of the form {{R|X and Y are related}}, parsing returns no edges by design — the integration needs directional verbs to build a flowchart.

Atlas / Vault Atlas blank

The atlas views render Def-tagged spans. If you've only used Q/A/M etc. with no Def, there's nothing to graph.

Debugging anything else: attach Obsidian's Electron debugger

If you want to inspect the live plugin state, launch Obsidian with the CDP port open:

/Applications/Obsidian.app/Contents/MacOS/Obsidian --remote-debugging-port=9222

Then in another terminal:

curl -s http://127.0.0.1:9222/json | head

Pick the page entry whose URL contains obsidian.md, grab its webSocketDebuggerUrl, and connect with any CDP client. For one-off probes, this Node script works:

// /tmp/probe.mjs
const TARGETS = await (await fetch('http://127.0.0.1:9222/json')).json();
const page = TARGETS.find(t => t.type === 'page' && t.url?.includes('obsidian.md'));
const ws = new WebSocket(page.webSocketDebuggerUrl);
const pending = new Map();
let nextId = 1;
const call = (method, params={}) => new Promise(r => {
  const id = nextId++;
  pending.set(id, r);
  ws.send(JSON.stringify({ id, method, params }));
});
ws.addEventListener('open', async () => {
  await call('Runtime.enable');
  const res = await call('Runtime.evaluate', {
    expression: process.argv[2] || '1+1',
    returnByValue: true,
    awaitPromise: true,
  });
  console.log(JSON.stringify(res.result, null, 2));
  ws.close();
});
ws.addEventListener('message', e => {
  const m = JSON.parse(e.data);
  if (m.id && pending.has(m.id)) { pending.get(m.id)(m.result); pending.delete(m.id); }
});

Run as node /tmp/probe.mjs 'app.plugins.plugins["semantic-reading"].api.queries.tagCounts()'.

This was how the 1.3.1 Sheet/Gaps bug was actually found.

File a bug

If none of the above match, open an issue at https://github.com/DavidTbilisi/obsidian-semantic-reading/issues. Helpful to include:

  • Plugin version (Settings → Community plugins → Semantic Reading → installed version).
  • Obsidian version (Cmd-P → Show debug info).
  • A minimal reproducible vault snippet (one note, the frontmatter, the tagged spans you used).
  • Console output (Cmd-Opt-I → Console tab).

See also

Clone this wiki locally