Troubleshooting

​

Symptoms

• Double-clicking ObsidianPortable.exe does nothing
• Application starts then immediately closes
• Error message appears on launch

​

Solutions

​

Symptoms

• Previously opened vault doesn’t appear in the vault list
• “Open folder as vault” doesn’t work
• Vault path shows error

​

Solutions

1. Open Data/ObsidianAppData/obsidian.json in a text editor
2. Look for vault entries with old drive letters
3. Either:
   • Manually update paths to current drive letter
   • Re-open the vault using “Open folder as vault”

• .obsidian/ directory (may be hidden)
• Markdown files (.md)

1. In Obsidian, choose “Open folder as vault”
2. Navigate to the vault folder
3. Select the folder to re-add it to the vault list

​

Symptoms

• Theme changes don’t save
• Plugin configurations reset
• Custom hotkeys disappear

​

Solutions

ObsidianPortable/
└── Data/
    └── ObsidianAppData/
        └── obsidian.json

1. Right-click the Data/ folder
2. Select Properties → Security
3. Ensure your user has “Modify” permission

--user-data-dir="Data/ObsidianAppData"

1. Right-click ObsidianPortable folder
2. Properties → ensure “Read-only” is not checked
3. If on USB drive, check drive properties

​

Symptoms

• Vaults show “path not found” error
• Recently opened vaults have wrong drive letters
• Can’t access vaults that worked before

​

Solutions

1. Close Obsidian completely
2. Delete Data/ObsidianAppData/obsidian.json
3. Relaunch Obsidian Portable
4. Re-open your vault using “Open folder as vault”

{
  "vaults": {
    "vault-id": {
      "path": "E:\\MyVault",
      "ts": 1234567890
    }
  }
}

1. Initial data directory placeholder
2. Package location changes (folder renamed/moved)
3. PortableApps base directory changes
4. Drive letter changes

​

Symptoms

• Obsidian takes long to launch
• Slow typing or editing
• Delayed file opening
• High CPU or memory usage

​

Solutions

• USB 2.0: Very slow - upgrade to USB 3.0+
• USB 3.0: Acceptable for basic use
• SSD/NVMe: Best performance
• Network drives: Speed varies; test with local drive first

1. Split large vaults into smaller, focused vaults
2. Archive old notes to separate vaults
3. Remove unused attachments and files

1. Open Settings → Community plugins
2. Disable plugins you don’t actively use
3. Test performance after each change to identify culprits

1. Move large attachments outside the vault
2. Link to files rather than embedding them
3. Use external folders for media storage

1. Close Obsidian
2. Navigate to Data/ObsidianAppData/Cache/
3. Delete cache files
4. Restart Obsidian

​

Symptoms

• Community plugins won’t install
• Installed plugins don’t appear
• Plugin errors in console
• Plugins disabled on restart

​

Solutions

YourVault/.obsidian/plugins/

1. Download plugin from GitHub releases
2. Extract to YourVault/.obsidian/plugins/plugin-name/
3. Ensure the folder contains:
   • manifest.json
   • main.js
   • styles.css (if applicable)
4. Restart Obsidian
5. Enable plugin in Settings → Community plugins

1. Check plugin documentation for version requirements
2. Update Obsidian Portable to the latest version
3. Report compatibility issues to plugin developers

​

Symptoms

• Installed theme doesn’t appear
• Theme changes don’t take effect
• Theme looks broken or incomplete

​

Solutions

YourVault/.obsidian/themes/theme-name/
├── manifest.json
└── theme.css

1. Settings → Appearance
2. Under “Themes”, select your installed theme from the dropdown
3. Reload Obsidian if needed

1. Close Obsidian
2. Delete YourVault/.obsidian/appearance.json
3. Restart Obsidian and reselect theme

1. Settings → Appearance → CSS snippets
2. Disable all snippets
3. Test if theme works
4. Re-enable snippets one by one to identify conflicts

1. Settings → Appearance → Manage themes
2. Find the theme and click “X” to uninstall
3. Reinstall the theme
4. Select it from the themes dropdown

​

Symptoms

• Duplicate files with “conflict” in the name
• Settings reverting unexpectedly
• Vault corruption or missing notes
• Sync service showing conflicts

​

Solutions

1. Always close Obsidian before syncing
2. Wait for sync to complete before opening on another device
3. Check sync status before launching

1. Close before sync: Always exit Obsidian before allowing sync
2. One device at a time: Only use on one computer at a time
3. Wait for completion: Let sync finish before moving to another device
4. Monitor sync status: Watch for sync errors or conflicts
5. Regular backups: Keep separate backups outside cloud storage

• Use Obsidian’s official sync service
• Handles simultaneous access safely
• Provides version history and conflict resolution
• End-to-end encrypted

​

Symptoms

• Settings reset when moving to new computer
• Vault list is empty after moving drive
• Have to reconfigure everything on each computer

​

Solutions

--user-data-dir="Data/ObsidianAppData"

1. Launch Obsidian Portable
2. Open Task Manager
3. Right-click Obsidian process → Properties
4. Check command line includes --user-data-dir

ObsidianPortable/
└── Data/
    └── ObsidianAppData/

[Launch]
CommandLineArguments=--user-data-dir="%PAL:DataDir%\ObsidianAppData"