Diagnose and fix common Obsidian plugin errors and exceptions.
Use when encountering plugin errors, debugging failed operations,
or troubleshooting Obsidian plugin issues.
Trigger with phrases like "obsidian error", "fix obsidian plugin",
"obsidian not working", "debug obsidian plugin".
Diagnose and fix common Obsidian plugin errors and exceptions.
Use when encountering plugin errors, debugging failed operations,
or troubleshooting Obsidian plugin issues.
Trigger with phrases like "obsidian error", "fix obsidian plugin",
"obsidian not working", "debug obsidian plugin".
allowed-tools
Read, Grep, Bash(node:*)
version
1.13.0
license
MIT
author
Jeremy Longshore <jeremy@intentsolutions.io>
tags
["saas","obsidian","debugging"]
compatibility
Designed for Claude Code, also compatible with Codex and OpenClaw
Obsidian Common Errors
Overview
Diagnostic guide for the six most frequent Obsidian plugin development errors, with root causes and copy-paste fixes.
Prerequisites
Obsidian plugin development environment set up
Access to Developer Console (Ctrl/Cmd+Shift+I)
Plugin source code access
Instructions
Step 1: "Cannot read properties of null" — Workspace Not Ready
Accessing app.workspace.activeLeaf or app.workspace.getActiveViewOfType() before the layout is initialized returns null.
Obsidian auto-loads styles.css from the plugin root directory. It must be named exactly styles.css (not style.css, not in a subdirectory).
set -euo pipefail
# Verify all three required files exist in plugin rootls -la styles.css manifest.json main.js
If you use a CSS preprocessor, ensure the build outputs to ./styles.css:
{"scripts":{"build:css":"sass src/styles.scss styles.css","build":"npm run build:css && node esbuild.config.mjs"}}
Common gotcha: the file must be styles.css (plural), not style.css.
Step 4: Commands Not Showing in Palette
Commands registered outside onload() or after the plugin is enabled won't appear in the command palette.
// BROKEN: adding command in a separate method called conditionallyasynconload() {
awaitthis.loadSettings();
// command never added because registerCommands is not called
}
registerCommands() {
this.addCommand({ id: 'test', name: 'Test', callback: () => {} });
}
// FIXED: add all commands directly in onloadasynconload() {
awaitthis.loadSettings();
this.addCommand({
id: 'test',
name: 'Test',
callback: () => {
newNotice('Working!');
}
});
}
If a command should only be available when a markdown file is open, use editorCallback instead of callback — Obsidian automatically hides it when no editor is active:
For vault files (TFile objects), use getAbstractFileByPath:
const file = this.app.vault.getAbstractFileByPath('notes/target.md');
if (file instanceofTFile) {
const content = awaitthis.app.vault.read(file);
// process content
} else {
newNotice('File not found: notes/target.md');
}
Step 6: Settings Not Persisting — Missing saveData Call
The most common settings bug: modifying the settings object without calling saveData.
// BROKEN: settings change lost on restartthis.settings.theme = 'dark';
// forgot to call saveData!// FIXED: always save after modifyingthis.settings.theme = 'dark';
awaitthis.saveData(this.settings);
Load settings with defaults to prevent undefined fields after plugin updates:
asyncloadSettings() {
// loadData() returns null on first run — Object.assign handles this safelythis.settings = Object.assign({}, DEFAULT_SETTINGS, awaitthis.loadData());
}
Object.assign merges saved data over defaults, so new fields added in later versions get their default value instead of undefined.
Output
Identified error matched to one of the six categories
Root cause explanation
Working code fix applied to plugin source
Error Handling
Error
Cause
Solution
TypeError: Cannot read properties of null
Workspace not ready
Use onLayoutReady or null-check
Plugin failed to load
Build error or bad manifest
Check console, verify manifest.json fields
CSS has no effect
Wrong filename or path
Must be styles.css in plugin root
Command missing from palette
Not added in onload()
Move addCommand into onload
Error: ENOENT on vault read
File doesn't exist
Check with adapter.exists() first
Settings reset on restart
Missing saveData call
Call saveData after every mutation
Examples
Quick Diagnostic Checklist
When a plugin fails to load, check these in order:
Open Developer Console (Ctrl/Cmd+Shift+I) and look for red errors
Verify main.js, manifest.json, and styles.css exist in plugin folder
Confirm manifest.json has id, name, version, minAppVersion
Confirm main.ts uses export default class
Rebuild with npm run build and reload Obsidian (Ctrl/Cmd+R)
Debug Logging Pattern
// Add to your plugin class for temporary debuggingprivatedebug(msg: string, ...args: any[]) {
if (this.settings.debugMode) {
console.log(`[${this.manifest.id}] ${msg}`, ...args);
}
}
