Skip to content

Troubleshooting and FAQ

Vivek Sarin edited this page Nov 18, 2026 · 4 revisions

Troubleshooting and FAQ

Troubleshooting

The diagram shows "FlowMotion: invalid diagram"

The text has an error. The message lists the problems and the line where each one occurs. Correct the line, and the diagram redraws. A text diagram must begin with a valid header line, such as flowchart TB. For the header list, see Writing diagrams.

The note shows "FlowMotion: file not found"

The diagram file was renamed or moved. Open the note in Source mode, and update the src: line to the new path. See Reusing diagrams.

FlowMotion does not appear in the community plugins list

  • Check that the FlowMotion folder is inside .obsidian/plugins/ in your vault.
  • Turn off Restricted mode in Settings, then Community plugins.
  • Restart Obsidian.

The diagram does not start

  • Click the diagram to start it.
  • Check the Autoplay setting under Settings, then FlowMotion.
  • Check whether the diagram sets %% @autoplay off. See Playback and timing.

The diagram looks too large or too small

Change the screen mode, or set height or width. See Appearance and backgrounds.

The draw.io editor says it is not installed

Turn draw.io editor off and on again in FlowMotion settings to download the add-on, then reopen the drawing. If the download fails, the notice names the reason (for example, no network). Check for <vault>/.obsidian/plugins/flowmotion/drawio/index.html, then reopen the drawing. See Settings.

The diagram editor does not show Monaco suggestions

CodeMirror is the default editor and includes YAML highlighting and a live preview. On desktop, enable Rich Code Editor (Monaco), wait for installation, and reopen the diagram. Note-source language support does not depend on Monaco.

The draw.io add-on says "Status: unknown."

FlowMotion could not check the add-on files. Open Obsidian's developer console for the logged error. Check access to the plugin folder, then reopen settings.

E2E setup fails on macOS with xattr -cr

Obsidian's installer setup needs Apple's /usr/bin/xattr. Python can install a different xattr earlier in PATH; that version rejects -r.

The current wdio.conf.mts prioritizes /usr/bin for macOS test processes. Update to the current configuration and rerun make test-e2e. The single-worker configuration inherits the same fix. No Python uninstall or system-wide shell change is required.

If the error persists, compare the selected executables:

which -a xattr
/usr/bin/xattr -h

E2E tests cannot find settings controls

Newer desktop versions can put Settings in a separate window. The E2E helpers switch to that window before querying controls. Dropdown selectors also exclude Obsidian's hidden .is-measuring copy.

If a custom test hangs while updating add-on status, check whether it calls setting.setDesc() asynchronously during rendering. The plugin updates descEl.textContent instead to avoid a re-render loop. See Obsidian plugin.

For test commands, version coverage, and Linux setup, see Testing and examples.

The installation commands fail

  • Check that Node.js is installed. Type node --version in the terminal. If the command is not found, install the LTS version from nodejs.org.
  • Check that you are in the FlowMotion folder before you run npm install.
  • Check that the vault path in npm run install-plugin is in quotation marks, and that it is correct.

Frequently asked questions

Does FlowMotion need an internet connection?

Only to install the optional draw.io or Monaco editor. Diagrams and storyboards work offline, as do the add-ons after installation. FlowMotion does not need an account and does not send your diagrams to a cloud service.

Turning on draw.io editor downloads the add-on from the draw.io GitHub releases. After that it works offline.

Is FlowMotion a desktop-only plugin?

Yes. manifest.json sets isDesktopOnly to true, and the code editor and draw.io editor need desktop Obsidian.

Can I use FlowMotion in Obsidian's presentations?

Yes, with some limits. See Presentations.

Where are the diagrams stored?

Inline diagrams are stored inside the note, in the flowmotion block. Diagrams in .flow and draw.io files are stored in their own files in your vault.

Can I report a problem or suggest a feature?

Yes. Open an issue on the FlowMotion GitHub page.

Clone this wiki locally