Contents

Troubleshooting

Common Issues

•7 min read
Common Issues

Common Issues

Solutions to frequently encountered problems.

Installation

"Cannot be opened because Apple cannot check it"

RiteMark isn't notarized with Apple yet. To open:

  1. Right-click on RiteMark in Applications
  2. Select Open
  3. Click Open in the dialog

You only need to do this once.

App won't open at all (macOS)

  1. Verify you have an Apple Silicon or Intel Mac
  2. Try downloading the DMG again
  3. Move to Applications folder before opening

Windows SmartScreen blocks the installer

Windows may show a "Windows protected your PC" warning for new applications. This is normal. See our Windows SmartScreen guide for step-by-step instructions to get past it.

Editor

Blank editor / Nothing shows

The editor webview didn't load. Try:

  1. Reload Window: Cmd+Shift+P -> "Reload Window"
  2. Restart RiteMark: Quit and reopen
  3. Check file type: Only .md files open in WYSIWYG mode

Changes not saving

RiteMark auto-saves after 1 second. If changes aren't saving:

  1. Check file permissions (can you write to that folder?)
  2. Look for error messages in bottom status bar
  3. Try saving manually: Cmd+S

Formatting looks wrong

  1. Reload the window: Cmd+Shift+P -> "Reload Window"
  2. Check if the file is valid markdown
  3. Complex HTML in markdown may not render correctly

Text selection issues

  1. Click outside the editor, then back inside
  2. Reload window if persistent

Markdown opens as plain text, or a Restricted Mode banner appears

Fixed in v1.8.6. On some fresh installs, double-clicking a .md file asked whether you trust the authors of the files in the folder, then opened the file as plain-text code with a Restricted Mode banner across the top of the window instead of the formatted editor.

Update to v1.8.6. A double-clicked markdown file opens straight in the Ritemark editor with no trust dialog and no banner, and a profile that was already stuck in this state repairs itself on the first launch after the update.

AI Assistant

"AI Offline" in status bar

The AI assistant can't connect. Check:

  1. Internet connection - Are you online?
  2. API key - Is one configured?
  3. API credits - Do you have OpenAI credits?

No response from AI

  1. Wait longer - some requests take time
  2. Check for error messages in the AI sidebar
  3. Try a simpler request
  4. Verify your API key is valid

"Invalid API key" error

  1. Cmd+Shift+P -> "Configure OpenAI API Key"
  2. Enter a valid key (starts with sk-)
  3. Make sure no extra spaces were copied

AI changes wrong text

  1. Select text first before making a request
  2. Check the selection indicator in the AI sidebar
  3. Be specific about what you want changed

Claude Code not working on Windows

Earlier versions of RiteMark had binary detection issues on Windows where .cmd/.exe shims were not resolved correctly, causing "spawn EINVAL" errors in AI chat. This is fixed in v1.5.0. Update RiteMark and check Settings -> Claude Account to confirm Claude Code shows as connected.

Codex not working on Windows

The same binary detection fix in v1.5.0 applies to Codex. Update RiteMark and check Settings -> ChatGPT Account for your connection status.

"spawn EINVAL" error in AI chat

This error occurred on Windows in versions before 1.5.0 due to incorrect .cmd to cli.js resolution. The fix is to update RiteMark to v1.5.0 or later. After updating, the AI agents should connect without errors.

"Some agent features are unavailable" banner

Some versions before v1.7.0 showed a "Some agent features are unavailable" banner because the Codex compatibility probe only tried one argv shape. Update to v1.7.0 or later -- the probe now tries both shapes, and the false warning is gone.

Want to use a system-installed Claude or Codex

As of v1.7.0, Settings -> Agent Runtime lets you choose between the bundled CLI (default) and the version installed on your system PATH. Switch any time without restarting. The active binary path is shown live in Settings.

The offline banner keeps flickering

Fixed in v1.8.6. Earlier builds called the app offline after a single failed check, so one blip on a healthy connection was enough to flash the banner. Connectivity now races several independent endpoints, any response at all counts as online, and it takes two consecutive failed rounds before the banner appears. Recovery is instant.

Fixed in v1.8.6. When an agent refers to a file in your open folder, that reference is a link and clicking it opens the file in Ritemark. Line-anchored references written as README.md:12 are handled too.

The agent edited files while it was supposed to be planning

Not possible from v1.8.6 onward. Plan mode is enforced by the runtime rather than requested of the model, so a planning agent has no write capability at all. The review card reports No files changed yet as a fact. See Plan Mode.

If you saw this on an older build, update. Approving a plan now hands over at exactly the autonomy you chose, Manual or Auto, with no silent escalation.

Scheduled agents started running without being asked

Fixed in v1.8.6. A folder that defines scheduled AI agents now asks once before anything is armed, and the answer is reversible any time from the Agent Library. Folders that were already using scheduling before the update keep working as they were.

Export

PDF export fails

  1. Check you have write permission to save location
  2. Try saving to Desktop first
  3. Make sure document isn't corrupted

Word export has wrong formatting

  1. Complex tables may need manual adjustment
  2. Some markdown features don't translate perfectly
  3. Consider PDF for consistent formatting

Export button not visible

Export only works for markdown files. CSV and Excel files use different tools.

Files

CSV file shows as text

  1. Make sure file extension is .csv
  2. Close and reopen the file
  3. Check file isn't corrupted

Excel file won't open

  1. Verify extension is .xlsx or .xls
  2. File might be corrupted - try opening in Excel
  3. Very large files may fail to load

Large file warning

Files over 5MB or 10,000 rows may:

  • Take longer to load
  • Be truncated (CSV shows first 10K rows)
  • Cause performance issues

For very large data, use a dedicated spreadsheet app.

Performance

Slow typing / lag

  1. Close other resource-heavy applications
  2. Reload window: Cmd+Shift+P -> "Reload Window"
  3. Very long documents may be slower

High memory usage

  1. Close unused files
  2. Restart RiteMark
  3. This is a known issue being improved

Updates

Using the Update Center

As of v1.5.0, RiteMark includes an Update Center in Settings. You can check for available updates, install them directly with pause and resume support, skip versions you don't want, and see component readiness cards showing what's included in each update. This is the recommended way to keep RiteMark current.

Finder shows the wrong version number

Fixed in v1.8.6. Finder used to report the app bundle as "Ritemark.app (1.117.0)", which is the shell version rather than the Ritemark version. The bundle now carries the real version, so Finder, Get Info, and the About panel agree.

How to update manually

If you prefer to update manually or the Update Center isn't available (versions before 1.5.0), you can still download the latest release from the GitHub releases page. On macOS, open the DMG and drag RiteMark to Applications to replace the existing version. On Windows, run the new Ritemark-Setup.exe installer.

Still Stuck?

Get Help

Report an Issue

If you've found a bug:

  1. Note what you were doing
  2. Note any error messages
  3. Check if it's reproducible
  4. Report at GitHub Issues

Quick Fixes

Problem Quick Fix
Editor blank Cmd+Shift+P -> Reload Window
AI not working Check internet + API key
Can't open app (macOS) Right-click -> Open
SmartScreen warning (Windows) Click More info -> Run anyway
File won't save Check folder permissions
Slow performance Restart RiteMark
AI agents not working (Windows) Update to v1.5.0, check Settings -> Account sections
Markdown opens as plain text / Restricted Mode Update to v1.8.6, relaunch once
Offline banner flickering Update to v1.8.6
Scheduled agents armed without asking Update to v1.8.6, manage them in the Agent Library
Back to support