---
title: "Troubleshooting"
description: "Find the next useful action when a file, preview or connection behaves unexpectedly."
canonical: https://editmd.app/docs/troubleshooting/
markdown: https://editmd.app/docs/troubleshooting.md
status: pre-release, waiting list open
generated: editmd-website
---

# Troubleshooting

Find the next useful action when a file, preview or connection behaves unexpectedly.

## The app will not open

Check the [installation steps](/docs/install/) and the full macOS message. Confirm you opened the copy in Applications and that the package matches your Mac. Stop if macOS rejects the download's integrity or developer verification; do not bypass the warning.

## My Markdown looks like plain text

Choose **Split** or **Preview**. Confirm the syntax has spaces where required: `# Heading`, not `#Heading`. Close any unclosed backtick fence and add blank lines between blocks. The [writing reference](/docs/writing/) includes examples.

## An image is missing

Check the image's relative path and whether the attachment moved with the document. Remote preview images are off by default. Exports block remote resources even if the preview can show them, so use a local attachment and check the exported result.

## A file will not open

editmd reads UTF-8 text files. A file saved in another encoding is reported as unavailable; open it in another editor and save it as UTF-8. Files reached through a symbolic link are refused; open the real file instead.

## A diagram or formula does not render

Check the block language and syntax. Try a smaller example to locate the error. Complex or unsupported content may remain as source rather than a rendered diagram. Different export formats also have different capabilities.

## My changes disappeared or a conflict appeared

Check the active tab and file location first. Look for a recovery notice or external-change conflict. Another editor or sync service may have changed the same file. Preserve any useful text before resolving the conflict, and check your backup or sync version history if needed.

## An AI model is missing

For OpenRouter, use **Load compatible models**; the app only offers candidates that meet its route requirements. For Ollama, start the local service and use **Refresh installed models**. A model must be installed through Ollama before editmd can select it.

## AI connects, but an action is unavailable

Ollama exposes grounded **Ask** only. OpenRouter and local models need the appropriate successful test for the selected model in the current app session. Test again after changing models. If structured output or grounding checks fail, choose another compatible model.

## The AI answer is wrong

Compare it with the source. Reject edits that change meaning or add unsupported facts. Try a smaller, clearer scope if you want another attempt. Passing a connection test does not make every answer correct.

## What to include when reporting a problem

Record the editmd version, macOS version, Apple silicon or Intel, the exact message, the steps that led to it and what you expected. Try a small synthetic document that reproduces the problem. Include a screenshot only after removing private text, file paths, provider credentials and account details.

You do not need to send your full workspace to explain a bug.

Group: Reference. Handbook index: https://editmd.app/docs.md