Troubleshooting

This is the first place to look when something isn’t working. If your issue isn’t covered here, check the FAQ or email support@pensum.dev.

Setup and loading

”Pensum requires a newer version of Obsidian”

Pensum needs Obsidian 1.11.4 or later because it uses the SecretStorage and SecretComponent APIs introduced in that release. Update Obsidian (Settings → About → Check for updates) and re-enable the plugin.

If you can’t update Obsidian for some reason, you’ll need to wait — there’s no fallback path; SecretStorage isn’t available on older versions.

”No tasks indexed yet” / empty views on first load

Pensum scans your vault on startup. For large vaults (5,000+ files) this takes a few seconds; for very large vaults (50,000+) it can take a minute. The views show the empty state until the scan finishes.

If the scan seems stuck, run Pensum: Rescan vault from the command palette to retry. Check Obsidian’s developer console (Ctrl+Shift+I) for errors.

Tasks not appearing in views

Pensum recognizes any line matching the standard Tasks-plugin syntax:

• Must start with - [ ] (open), - [x] (completed), - [/] (in-progress), or other status chars
• Must be in a .md file inside your vault
• Must not be in a hidden folder (a folder starting with .)

Numbered lists (1.), other checkbox shapes (* [ ]), or non-markdown files are not scanned. If you’re using a non-standard task syntax via another plugin, Pensum won’t see those tasks.

Run Pensum: Rescan vault after fixing the syntax to pick up the changes.

”Hotkey not working”

Pensum doesn’t ship pre-bound hotkeys (Obsidian asks plugins not to claim shortcuts at install). Open Settings → Hotkeys → search “Pensum” and confirm the command actually has a binding.

If the binding exists but isn’t firing, another plugin (or Obsidian itself) likely claimed the same shortcut — the Hotkeys panel highlights the conflict. The hotkey reference lists the combinations Pensum recommends.

Index and scanning

Stale data in views

Pensum keeps the index up to date as you edit files. If a view shows old data after you’ve edited a file outside Obsidian (via git pull, another editor, or sync), run Pensum: Rescan vault to reconcile.

For routine in-Obsidian edits, the file watcher updates the index automatically within a couple of seconds.

Index file is corrupted or missing

Pensum stores an internal index at .pensum/index.json in your vault. If this file is corrupted (vault sync interrupted mid-write, manual edit gone wrong), Pensum may show “No entities indexed” or hang on startup.

Delete .pensum/index.json and run Pensum: Rescan vault. The index is regenerated from your markdown files. No data is lost — the index is a derived artifact, not a source of truth.

Sync conflicts in the index file

If you sync your vault across devices, .pensum/index.json can occasionally collide (two devices both edited it before sync). The conflict file (.pensum/index.json.conflict-...) is safe to delete. Then run Pensum: Rescan vault on each device to converge.

To avoid this entirely, you can exclude .pensum/index.json from your sync — Pensum will regenerate it on first run on each device. The trade-off is the first scan after install takes longer.

AI features

”Smart Capture / Triage / Summary unavailable” notice

The most common causes:

1. No AI key configured (Pro BYO) — go to Settings → AI → Providers, add your secret name for the relevant provider. Click Test to verify.
2. Wrong provider for the chosen model — if Settings → AI → Smart Capture has a Claude model selected but you only have an OpenAI key, the call fails. Either switch models or add the right key.
3. Trial expired (you were on Pro All-in-One via trial) — Settings → Account shows your plan; subscribe or switch to BYO.
4. License revalidation failed — Pensum checks in with the license server every ~7 days. If your network was down or the server returned an error, you’ll see a “managed AI authorization failed” notice. The 30-day offline grace period covers transient outages.

Click the action link in the failure notice — it’ll deep-link to the relevant settings section.

”Provider error” / 401 / 403 from Anthropic, OpenAI, etc.

• 401 — your API key is invalid, expired, or you copy-pasted with extra whitespace. Re-enter the secret in Obsidian’s keychain.
• 403 — your account doesn’t have access to the model you selected. Either switch models or update your provider account.
• 429 — rate limited. Wait and retry, or switch providers / increase your account tier with the provider.

Smart Capture is slow

The default Smart Capture model (Claude Haiku 4.5) responds in under a second on a good network. If you’re seeing 3-5+ second pauses:

• Check your network speed
• Check the provider’s status page for incidents
• Try a different model (Settings → AI → Smart Capture)
• If you’re on managed mode, the Pensum proxy adds ~100ms of overhead — usually irrelevant, but check the Activity log if it’s much higher

Transcription fails

Requires an active provider:

• Managed (Pro All-in-One / Trial): Pensum’s proxy handles it. If it’s failing, the Activity log will show the error code.
• BYO Deepgram: You need a Deepgram API key configured. Get one at deepgram.com.
• BYO OpenAI (Whisper / gpt-4o-transcribe): You need an OpenAI API key with audio API access.

Other things to check:

• Audio file exists at the path in the meeting note’s recording: frontmatter
• Audio file isn’t corrupted (try playing it in Obsidian or your OS file browser)
• Very long recordings (>2 hours) may approach provider limits — split into multiple recordings

Transcription is wildly wrong

• Speaker labels off — the diarization model is approximating; run Identify Speakers to map labels to names from your attendees list
• Whole words missing — likely a low-volume speaker. Re-record with mic placement closer to all speakers, or accept that no transcription model is perfect
• Wrong language detected — most providers default to auto-detect; if you need a specific language, the BYO path lets you pass language hints (managed currently uses auto-detect)

License and account

”Could not reach license server”

The plugin tries to revalidate your license every ~7 days. If it can’t reach api.pensum.dev, it falls back to the cached license for up to 30 days (the offline grace period).

If you’re hitting this repeatedly:

• Check that your network can reach api.pensum.dev (try opening it in a browser)
• Check for corporate firewall / VPN that might be blocking
• Wait 24 hours and try again — Cloudflare-side incidents are rare but possible
• Contact support@pensum.dev if it persists past the grace period

”Maximum devices reached”

Each license supports 5 active devices. To free a slot:

• Open Settings → Account → Devices on the device you want to revoke and click Revoke (when this UI ships in a future release)
• For now: email support@pensum.dev with your license key and the device name you want removed

License key valid but Pro features are locked

• Try Settings → Account → Validate to force a re-check
• The plan tag at the top of Settings → Account should show “Pensum Pro” — if it shows “Free”, the license key didn’t validate
• Make sure you didn’t paste the key with extra whitespace

CLI

”No vaults configured”

Run pensum config init to bootstrap from your Obsidian installation, or create ~/.config/pensum/config.toml manually:

default = "personal"

[vaults.personal]
path = "~/vaults/personal"

See CLI commands for the full config schema.

CLI slow on large vaults

The CLI scans your vault on each invocation. For large vaults this takes a few seconds on first run. Subsequent runs use the persisted index file (.pensum/index.json) for near-instant responses.

If even subsequent runs are slow, the index might be stale or corrupted. Run pensum doctor to verify — it shows the file count, last scan time, and reconciliation results. Delete .pensum/index.json and re-run if it looks off.

Output is JSON when you wanted a table

The CLI auto-detects TTY. If you’re piping or redirecting, you get JSON. To force the human-readable rich mode:

pensum task today | less -R    # WRONG: pipes get JSON
pensum task today                # right: TTY-attached gets rich
PENSUM_FORMAT=rich pensum task today | less -R   # force rich even when piped

--plain gives you tab-separated text (good for grep/awk). --json gives you the structured envelope.

MCP

Agent says “Pensum tools not available”

• The MCP server config snippet didn’t make it into your client. Double-check via pensum mcp-config.
• The path in PENSUM_VAULT is wrong or unreadable. Use an absolute path; check permissions.
• The client wasn’t restarted after editing the config. Restart it.
• Pensum binary isn’t on your PATH from the client’s perspective (some MCP clients use restricted shells). Use the full path to the pensum binary in command: instead of relying on PATH lookup.

Tasks captured by an agent aren’t showing up

By default, agent-captured tasks land in the Agent Captures view with agent-suggested-pending provenance. They don’t show in Today / Inbox / By Project until you accept them.

Open Pensum: Open agent captures to review and accept. Or turn off the review queue in Settings → Agents → Agent capture review if you want agent captures to bypass review.

Mobile

Recording on iOS / Android stops when I switch apps

This is a platform limitation, not a Pensum bug. iOS and Android suspend WebView audio capture aggressively when the app loses foreground. Keep Obsidian foregrounded during recording. The audio captured before suspension is still saved.

Sync conflicts on the audio file

Audio files are large and prone to conflicts if you’re syncing during recording. Pause your sync (Obsidian Sync, Syncthing, etc.) while recording on mobile if you’re seeing this.

Transcription on mobile

Transcription is deferred to desktop by default on mobile. The plugin captures the audio and meeting note; the next time you open the vault on a desktop with Pro, you can run Transcribe there.

This is intentional — mobile transcription is slow, expensive on data, and battery-hungry. Desktop handles it better.

Still stuck?

• Email support@pensum.dev — include your OS, Obsidian version, Pensum version, and what you tried.
• GitHub issues at github.com/craigmccaskill/pensum/issues for plugin bugs — include reproduction steps.
• Check the developer console (Ctrl+Shift+I in Obsidian) — Pensum logs errors there, and the stack trace often points at the issue.