Solutions to frequently encountered problems.
Installation
"Cannot be opened because Apple cannot check it"
Ritemark for Mac is signed with its Developer ID and notarized by Apple (since v1.7.2), so this warning shouldn't appear for a download from the official releases page. If it does, the download is probably incomplete or came from somewhere else. Delete it and download the DMG again.
App won't open at all (macOS)
- Check you downloaded the build for your Mac: Ritemark-arm64.dmg for Apple Silicon, Ritemark-x64.dmg for Intel. Apple menu → About This Mac lists a Chip on an Apple Silicon Mac and a Processor on an Intel Mac
- Check your macOS version. Ritemark needs macOS 12 Monterey or later
- Try downloading the DMG again
- Move Ritemark to the Applications folder before opening it
Windows SmartScreen blocks the installer
Windows may show a "Windows protected your PC" warning when you run Ritemark-Setup.exe downloaded from GitHub. This is normal, and installing from the Microsoft Store avoids it. See our Windows SmartScreen guide for step-by-step instructions to get past it.
If Smart App Control or your organization's policy blocks the installer, keep Smart App Control turned on and install from the Microsoft Store instead, or ask your administrator for an approved way to install Ritemark.
Uninstall Ritemark
On a Mac, quit Ritemark, then drag Ritemark from Applications to the Trash. On Windows, open Settings → Apps, find Ritemark, and choose Uninstall.
Uninstalling leaves your documents alone, because they are ordinary files in your folders. It also keeps Ritemark's settings in case you install it again. To remove the settings and downloaded models as well, delete ~/Library/Application Support/Ritemark and ~/.ritemark on a Mac, or %APPDATA%\Ritemark and %USERPROFILE%\.ritemark on Windows.
Editor
Blank editor / Nothing shows
The editor webview didn't load. Try:
- Reload Window: Cmd+Shift+P -> "Reload Window"
- Restart Ritemark: Quit and reopen
- Check file type: Only
.mdfiles open in WYSIWYG mode
Changes not saving
Ritemark auto-saves after 1 second. If changes aren't saving:
- Check file permissions (can you write to that folder?)
- Look for error messages in bottom status bar
- Try saving manually: Cmd+S
Formatting looks wrong
- Reload the window: Cmd+Shift+P -> "Reload Window"
- Check if the file is valid markdown
- Complex HTML in markdown may not render correctly
Text selection issues
- Click outside the editor, then back inside
- 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.
Images don't show in the editor
Fixed in v1.12.0. An image written with a plain relative path, like , or kept outside the document's own folder, like ../images/plan.jpg or one shared images/ folder at the top of a project, showed as blank or broken. Every image inside the folder you have open now shows in the documents in it. If you add a folder to the window while a document is already open, reopen that document to pick it up.
Saving a document with a ../images/… image also no longer writes an internal vscode-resource address into the file. The original path is kept, so the image works in other apps too.
Strikethrough disappears after saving
Fixed in v1.12.0. Text you struck through lost its line when the file was saved, so ~~done~~ came back as plain done. The strike is now written to the file. Literal tildes, such as ~/Downloads or ~5 min, are saved exactly as you typed them.
Typing a year at the start of a line makes a numbered list
Fixed in v1.12.0. Typing 2026. at the start of a paragraph turned it into a numbered list starting at 2026. Numbers up to 99 still start a list, and 100 and above stay a sentence. You can still start a list at any number from the toolbar or the slash menu.
Shift+End selects the rest of the document
Fixed in v1.12.0. Shift+End selected everything from the cursor to the end of the file, so the next keystroke could delete paragraphs further down without you noticing. Shift+End and Shift+Home now select to the end and the start of the line you're on.
AI Assistant
"AI Offline" in status bar
Ritemark can't reach the internet, and the AI sidebar needs a connection. Check:
- Internet connection - Are you online?
- Check again - Click it in the sidebar's offline banner to re-test the connection
No response from AI
- Wait longer - some requests take time
- Check for error messages in the AI sidebar
- Try a simpler request
- Check that the agent is signed in: Settings -> Claude Account or ChatGPT Account should show it as connected. For OpenCode, check that a provider key is saved in Settings
"Invalid API key" error
- Open Settings and find the key field for that provider (OpenAI, Google AI, Anthropic or OpenRouter)
- Paste a valid key again
- Make sure no extra spaces were copied
AI changes wrong text
- Select text first before making a request
- Check the selection indicator in the AI sidebar
- 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, Runtime preference under Settings -> Agent Runtime lets you choose between Bundled (the default) and Use system install, which prefers the Claude or Codex on your system PATH and falls back to the bundled copy. Under Currently active, Settings shows which copy each agent runs. On Windows, Ritemark asks for Git for Windows or Node.js only with Use system install, because the bundled Claude Code and Codex need neither.
Ritemark pauses for a few seconds at launch
Fixed in v1.12.0. Ritemark used to check Claude and Codex before the AI sidebar and your editors responded, and with a Codex you installed yourself the pause was about three seconds. The checks now run in the background.
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.
A file link in the AI chat does nothing
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.
As of v1.12.0, every link in a reply does something or says why not. A file outside your project is shown in Finder (File Explorer on Windows) rather than opened, a missing file names the path, and a link Ritemark doesn't open from chat, such as mailto:, says so and offers Copy link. See Links in the chat.
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.
Report AI issue doesn't open an email
Report AI issue in the status bar hands your report to your computer's email app. Ritemark never sends it itself. The report window tells you what happened, and your report always stays in it:
- If the window says Your email app is opening, find the new message in your email app, check it, and press Send there. The report isn't sent until you do.
- If it says No email app is set up on this computer, click Copy report under the text box and email the report to info@productory.eu from the address you normally use. This is expected on a computer without an email app. It isn't an error.
- If it says This report is too long to open in an email app, click Copy report and email it to info@productory.eu yourself. Email links can only carry a limited amount of text, so this way nothing is cut off.
If the window says your email app is opening but nothing appears, use Copy report the same way. The address is always shown under the text box as Write to us: info@productory.eu, so you can also write to it directly. See Report AI Output.
Export
PDF export fails
- Check you have write permission to save location
- Try saving to Desktop first
- Make sure document isn't corrupted
Word export has wrong formatting
- Complex tables may need manual adjustment
- Some markdown features don't translate perfectly
- Consider PDF for consistent formatting
Export button not visible
Export only works for markdown files. CSV and Excel files use different tools.
Publishing to Google Docs fails
Ritemark says why a Google Doc can't be created or synced, and offers the fix: reconnect your Google account, restore the Doc from the Drive trash, or remove the publishing link and create a new Doc. A failed Sync never changes your Markdown file. See When Something Goes Wrong.
Files
CSV file shows as text
- Make sure file extension is
.csv - Close and reopen the file
- Check file isn't corrupted
Excel file won't open
- Verify extension is
.xlsxor.xls - File might be corrupted - try opening in Excel
- 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.
A Word, PowerPoint or PDF file won't preview
The preview tells you why and offers another way to open the file. A Word document or presentation can't be previewed when it's larger than 50 MB, protected with a password, saved in the old .doc or .ppt format under a new name, or damaged. See When a File Can't Be Previewed.
Source Control
"Source control depends on Git being installed"
Source Control uses Git, a separate program that doesn't come with Ritemark. When Git isn't installed, the Source Control view says:
Source control depends on Git being installed. After installing Git, please reload (or troubleshoot).
The welcome page says the same: Ritemark needs Git. Install Git to use Source Control. Ritemark doesn't link to a Git download. It only tells you that Git is missing.
- Install Git yourself, for example from git-scm.com
- Back in Ritemark, click reload in the Source Control message, or run Reload Window (Cmd+Shift+P, or Ctrl+Shift+P on Windows)
- If Source Control still says Git is missing, click troubleshoot to see Git's log
Git is needed only for Source Control. The AI agents that ship with Ritemark don't need Git or Node.js, and as of v1.12.0 the welcome page mentions Node.js only on Windows, when Runtime preference is set to Use system install.
Performance
Slow typing / lag
- Close other resource-heavy applications
- Reload window: Cmd+Shift+P -> "Reload Window"
- Very long documents may be slower
High memory usage
- Close unused files
- Restart Ritemark
- 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
- Check Feature Documentation for how things should work
- Review Getting Started for setup steps
Report an Issue
If you've found a bug:
- Note what you were doing
- Note any error messages
- Check if it's reproducible
- Report at GitHub Issues
Quick Fixes
| Problem | Quick Fix |
|---|---|
| Editor blank | Cmd+Shift+P -> Reload Window |
| AI not working | Check internet, then sign-in or API keys in Settings |
| Can't open app (macOS) | Delete the download and get the DMG again from the releases page |
| SmartScreen warning (Windows) | Install from the Microsoft Store, or click More info -> Run anyway |
| Images blank in the editor | Update to v1.12.0; reopen the document after adding a folder to the window |
| Source Control says Git is missing | Install Git, then click reload |
| Report AI issue shows no email | Copy report, then email info@productory.eu |
| 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 |