Diagnostics

If the first run isn’t working, find your case in the table: next to it are the cause and what to check.

Symptom	Cause	Action
The program stays silent on startup	The wrong path, or the file doesn’t run	Confirm the file is at the given path and runs manually
The request went out, there’s no response, the process is alive	The core asked a counter-question and is waiting for an answer — this happens with operations that need the network	Read the line it sent: it has a kind field. Answer with a line carrying the same id. The core has no timeout of its own — the deadlineMs in its line is addressed to you — so it will wait indefinitely without an answer. Closing the input stream ends the wait with a refusal, not a hang (how the conversation works)
Opening returned ok=false — for an unparseable address, invalid-source-uri	An error in the file address, format, or access permissions	Pass the full file address, from the root — in Node.js, pathToFileURL from the node:url module gives you that; read code and message from the response
A stale revision — apply-cell-edits-stale-revision	A different request already changed the workbook	Request a fresh projection with the new revision number and deliberately retry the operation
The operation goes to the wrong sheet — unknown-sheet-key	A visible name was passed instead of the sheet key	Use activeSheet.path from the response to open
The saved file didn’t appear — invalid-destination-uri	An invalid destination address, or no write permission	Check the absolute URI and the folder
subsetId not found — unknown-subset-session	The core process was restarted and lost its open subsets	Call open_workbook_subset again
A formula shows a stale value — the cached-formula-preview warning	The workbook was just opened in a new process	This is the value saved in the file; to get a fresh one, trigger a recalculation. The core already told you this: check warnings in the response to open

What to attach to your request

• the SumSheet version and the platform;

• the sha512 checksum of the installer file — the one checked during installation;

• the operation name (operation) and the refusal code (code);

• the smallest anonymized XLSX workbook that reproduces it;

• one JSON request line and one JSON response line;

• whether it reproduces after a new process.

Send what you’ve gathered to hello@sumoffice.com — that’s enough to start triage without a follow-up email asking for what’s missing.

The response contents on a refusal — on the How the API session works page.