# Troubleshooting

Most OpenOnyx issues start with a file path, a vault state, an index, or an integration setting. Start with the smallest observable part.


## Why it exists

Local-first software gives you useful evidence: files, folders, settings, and reproducible actions. Troubleshooting works best when you inspect those before changing everything.

## When to use it

Use this page when a vault does not open, a note is missing, an index is stale, or an integration behaves unexpectedly.

## Workflow

Describe the symptom → confirm the vault path → reproduce with one note → inspect settings → report the smallest reproducible case.

## Checks

- [ ] The expected folder is open.
- [ ] The file exists in the filesystem.
- [ ] The note opens in another Markdown editor.
- [ ] The feature has the required index, permission, or integration setting.

> **OpenOnyx tip**
> Keep a small test vault. It makes it easier to tell an app issue from a vault-specific issue.

> **OpenOnyx common mistake**
> Back up before bulk renames, automated edits, or plugin migrations.

## Continue learning

- [Open a Vault](<Open a Vault.md>)
- [Privacy](<Privacy.md>)
- [Developer Guide](<Developer Guide.md>)