Troubleshooting

Work through the matching section below. Prefer in-app controls and reviewed diagnostics over hand-editing library files.

Phrase does not insert

1. Confirm Astramar has Accessibility permission (Accessibility permission).
2. Check whether the destination app is on Excluded Apps (Settings → Paste).
3. Try ⌘ Return to copy, then paste manually.
4. Switch paste method between standard paste and direct insert if one path fails in that app.
5. Quit and reopen Astramar after changing macOS permission.
6. Confirm you launched the build under Applications, not a temporary development path.

Palette does not open

1. Confirm the global palette hotkey under Settings → General / Palette controls.
2. Check for a conflicting macOS or application shortcut.
3. Try Open Phrase Palette from Settings or the menu bar.
4. If the panel appears off-screen, change Opening Position under Settings → Palette.

Trigger does nothing

1. Confirm Triggers enabled and that triggers are not paused (Settings → Triggers).
2. Confirm the per-kind toggle for that trigger type is on.
3. For autotext, type the trailing delimiter when required (Space / punctuation / Return).
4. Check collision chooser behavior — a shared abbreviation opens a chooser instead of inserting immediately (Triggers).
5. Review Settings → Advanced → All Triggers for disabled or conflicting rows when that panel is available.

Quick Add is missing

1. Enable Services → Add to Astramar in macOS Keyboard Shortcuts.
2. Quit and reopen Astramar and the source app.
3. Test in TextEdit first.
4. Create at least one folder if Quick Add says none exist.
5. Keep selections under 10,000 characters.

See Quick Add.

Library does not load / recovery appears

1. Do not hand-edit data.json or repeatedly replace it from Finder.
2. Use the recovery footer: restore a validated backup, import a .phrasepilot file, or start empty only after confirmation.
3. If the library was written by a newer app, install a compatible build instead of forcing an older one to rewrite it.
4. After recovery succeeds, quit and reopen.

Details: Library backups.

Save failed / quit blocked

Use Retry Save after fixing disk space or permissions, or Reveal Library Folder. On Quit while a save is failing, choose Quit Without Saving, Retry Save, or Cancel.

Reporting a problem

Follow Support. Export a metadata-only Diagnostic Summary from Settings → Library, review it, and never attach phrase libraries, clipboard content, tokens, or credentials to an ordinary public issue.