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

app.workspace.getActiveViewOfType()

null

// BROKEN: accessing workspace immediately in onload
async onload() {
  const view = this.app.workspace.getActiveViewOfType(MarkdownView);
  // TypeError: Cannot read properties of null (reading 'editor')
  view.editor.replaceSelection('hello');
}

// FIXED: wait for layout-ready event
async onload() {
  this.app.workspace.onLayoutReady(() => {
    const view = this.app.workspace.getActiveViewOfType(MarkdownView);
    if (view) {
      view.editor.replaceSelection('hello');
    }
  });
}

For commands that need workspace access later (not at load time), guard with a null check:

this.addCommand({
  id: 'my-command',
  name: 'Do Something',
  checkCallback: (checking: boolean) => {
    const view = this.app.workspace.getActiveViewOfType(MarkdownView);
    if (view) {
      if (!checking) {
        // safe to use view.editor here
        view.editor.replaceSelection('inserted');
      }
      return true;
    }
    return false;
  }
});

Step 2: "Plugin failed to load" — Syntax or Manifest Errors

This error appears in the console when Obsidian cannot parse your built

main.js

manifest.json

Check 1: Build output exists and compiles cleanly

set -euo pipefail
npm run build 2>&1
# Look for TypeScript errors in output
ls -la main.js  # Must exist in plugin root

Check 2: manifest.json has all required fields

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "minAppVersion": "0.15.0",
  "description": "Does something useful",
  "author": "Your Name",
  "isDesktopOnly": false
}

Missing

id

name

version

minAppVersion

id

.obsidian/plugins/

Check 3: Default export

// BROKEN: named export
export class MyPlugin extends Plugin { ... }

// FIXED: default export required
export default class MyPlugin extends Plugin { ... }

Step 3: CSS Not Loading — Wrong styles.css Path

Obsidian auto-loads

styles.css

styles.css

style.css

set -euo pipefail
# Verify all three required files exist in plugin root
ls -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

style.css

Step 4: Commands Not Showing in Palette

Commands registered outside

onload()

// BROKEN: adding command in a separate method called conditionally
async onload() {
  await this.loadSettings();
  // command never added because registerCommands is not called
}

registerCommands() {
  this.addCommand({ id: 'test', name: 'Test', callback: () => {} });
}

// FIXED: add all commands directly in onload
async onload() {
  await this.loadSettings();

  this.addCommand({
    id: 'test',
    name: 'Test',
    callback: () => {
      new Notice('Working!');
    }
  });
}

If a command should only be available when a markdown file is open, use

editorCallback

callback

this.addCommand({
  id: 'editor-only',
  name: 'Editor Only Command',
  editorCallback: (editor: Editor) => {
    editor.replaceSelection('inserted text');
  }
});

Step 5: Vault Read Errors — File Doesn't Exist

vault.read()

vault.cachedRead()

// BROKEN: assumes file exists
async readConfig() {
  const content = await this.app.vault.adapter.read('config.json');
  return JSON.parse(content);
}

// FIXED: check existence, handle missing file
async readConfig(): Promise<MyConfig> {
  const path = 'config.json';
  const exists = await this.app.vault.adapter.exists(path);
  if (!exists) {
    return { ...DEFAULT_CONFIG };
  }

  try {
    const content = await this.app.vault.adapter.read(path);
    return JSON.parse(content);
  } catch (e) {
    console.error('Failed to parse config:', e);
    return { ...DEFAULT_CONFIG };
  }
}

For vault files (TFile objects), use

getAbstractFileByPath

const file = this.app.vault.getAbstractFileByPath('notes/target.md');
if (file instanceof TFile) {
  const content = await this.app.vault.read(file);
  // process content
} else {
  new Notice('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 restart
this.settings.theme = 'dark';
// forgot to call saveData!

// FIXED: always save after modifying
this.settings.theme = 'dark';
await this.saveData(this.settings);

In settings tabs, save on every change:

new Setting(containerEl)
  .setName('Theme')
  .addDropdown(dropdown => dropdown
    .addOption('light', 'Light')
    .addOption('dark', 'Dark')
    .setValue(this.plugin.settings.theme)
    .onChange(async (value) => {
      this.plugin.settings.theme = value;
      await this.plugin.saveSettings();  // calls this.saveData(this.settings)
    }));

Load settings with defaults to prevent undefined fields after plugin updates:

async loadSettings() {
  // loadData() returns null on first run — Object.assign handles this safely
  this.settings = Object.assign({}, DEFAULT_SETTINGS, await this.loadData());
}

Object.assign

undefined

Output

• Identified error matched to one of the six categories
• Root cause explanation
• Working code fix applied to plugin source

Error Handling

TypeError: Cannot read properties of null

onLayoutReady

Plugin failed to load

manifest.json

styles.css

onload()

addCommand

onload

Error: ENOENT

adapter.exists()

saveData

saveData

Examples

Quick Diagnostic Checklist

When a plugin fails to load, check these in order:

1. Open Developer Console (Ctrl/Cmd+Shift+I) and look for red errors
2. Verify

   main.js

   ,

   manifest.json

   , and

   styles.css

   exist in plugin folder
3. Confirm

   manifest.json

   has

   id

   ,

   name

   ,

   version

   ,

   minAppVersion

4. Confirm

   main.ts

   uses

   export default class

5. Rebuild with

   npm run build

   and reload Obsidian (Ctrl/Cmd+R)

Debug Logging Pattern

// Add to your plugin class for temporary debugging
private debug(msg: string, ...args: any[]) {
  if (this.settings.debugMode) {
    console.log(`[${this.manifest.id}] ${msg}`, ...args);
  }
}

Resources

• Obsidian Developer Docs
• Obsidian Forum - Developers
• Obsidian Plugin Guidelines

Next Steps

For comprehensive debugging workflows, see

obsidian-debug-bundle