Diagnostics and checklist

If the first run isn’t working, find the symptom in the table: next to it is exactly what to check.

Symptom	What to check
Application not found	Installation path: /Applications/SumDoc.app on macOS, C:\Program Files\SumDoc on Windows (the folder could have been changed during installation), /opt/SumDoc on Linux — if you installed a deb or rpm package. The AppImage delivery has no installation folder: the files sit inside the image itself, and you can extract them with ./SumDoc-….AppImage --appimage-extract, then look in squashfs-root/resources/. Also check that you downloaded the build for your architecture
The processor doesn’t start	The application package is corrupted or wasn’t copied in full. On macOS and Linux, check that the file has execute permission
The response has ok: false	Read the error, cmd, and id fields: they say which command was refused and why. Check the file path and the operation’s fields
The file didn’t change	First, check result.mutation.result_kind in the response to the edit: only applied changed the document, while the envelope stays ok: true for invalid-request, invalid-target, not-found, and deferred too (how to read the response). Next, check whether you’re saving to a new path; what the revision and the unsaved-changes flag show; read the result again with the model-docx command
The surface disconnected	If you got an unmounted event you didn’t ask for, check whether you mounted a second surface: there’s only one per page, and a second mount unmounts the first (what the surface accepts and what it drops). Otherwise, check a page reload, the pass, the local interface port, the child process lifecycle, and reconnection after a drop
window.fastdocShell is undefined	The code is running outside the SumDoc application’s own window — those objects aren’t there. For embedding, use the external contract: JSON-line exchange, WebSocket, or the surface

First integration checklist

1. Find the installed application and fastdoc-cli inside it — paths for all three systems are given in Installation and verification.
2. On macOS and Linux, check that fastdoc-cli has the executable flag set; Windows has no such flag.
3. ping → ok: true, pong: true.
4. open with document_id given.
5. model — save the original text for comparison.
6. An edit with transaction_order: 1.
7. Save to a new output.docx.
8. Read output.docx again with the same processor.
9. Open output.docx in SumDoc and see the change.
10. shutdown and end the process.

Minimal integration is up

If both JSON-line exchange and WebSocket exchange work, the saved DOCX reads back from disk, and SumDoc shows the change on screen — minimal integration is up. The next step: choose the set of operations you need and lock them into a separate, versioned contract schema.

What to attach to your request

If the table above didn’t find the cause, write to hello@sumoffice.com. Triage is faster when the message already has:

• the SumDoc build version and the system where you see this;
• the command name (cmd) and the full refusal text (error), together with the request id;
• one request line and one response line as they are, not paraphrased;
• the smallest anonymized DOCX that reproduces it;
• whether it reproduces in a new process — after shutdown and a fresh start.

Where to look next

• The request and response format, including fields that may be absent — Request and response objects.
• The full list of commands with parameters — the Session Protocol reference.
• Transport refusal codes and text — SumDoc transport and message format.
• Behavior after a dropped connection — Embedding Surface.