Troubleshooting

Symptom first, then what it means and what to do. Each entry stands alone.

"Let this site edit files in MyNotes?" appears every time I open a local graph

The browser forgets a website's permission to a folder when it closes, so it asks once per session. Nothing is wrong and your files are untouched. Install EtherPK as an app and the permission is kept (Installing EtherPK As An App).

There is no Open folder button

This browser cannot open a local folder. Only Chromium-based desktop browsers (Chrome, Edge, Brave) have the feature, and a managed work computer can have it switched off by policy even there. The Knowledge graphs page says which case applies. Use Chrome or Edge, or a synced graph, which works in every browser (Running EtherPK On Your Own Computer has the policy check).

"Could not save" with a Retry button

A write to a local graph's file failed: the disk is full, the folder's permission lapsed, another program has the file locked, or the folder is no longer where it was. The notice says which. Your edits are kept in the tab until a save succeeds, so fix the cause and select Retry saving. Do not close the tab first.

"External change": a file changed on disk while you have unsaved edits

Another program, a sync tool or an agent wrote the file while you were editing it in EtherPK. Choose Keep mine to write your version over the file, or Take disk to load theirs and drop your unsaved edits. EtherPK never merges the two (Local Graphs).

A page's title changed by itself

Something outside EtherPK changed the title: in the file's frontmatter. EtherPK follows the file and shows a notice. Links to the old name are not rewritten; use Rename… if you want them updated, or add the old name as an alias (Titles Aliases And Frontmatter).

"This graph is on your account but not set up in this browser"

The browser lost its record of a synced graph, usually because it cleared storage to free space. Your notes are safe on the server. Select Set it up here, or Add to this device on the Knowledge graphs page. If EtherPK restored the record itself, a notice headed "Your browser cleared some of EtherPK's data on this device" says what came back (Recovery Code And Device Approval).

A synced graph opens but will not read my notes

The keys held on this device are stale. Sync settings > Lock keys, then Unlock keys, by approving from another device or with your Recovery Code. Nothing is lost. Do not reset your encryption keys for this.

A phone keeps forgetting graphs or passkeys

The phone's browser is clearing EtherPK's storage to free space. EtherPK restores the list of graphs and your passkeys and downloads documents again, but edits that had not reached the server can be lost. Install EtherPK to the home screen so the browser keeps its storage, and check Sync settings > Storage on this device (EtherPK On A Phone).

"Sync unavailable" in the header

The Sync Server could not be reached, or your sign-in could not be confirmed. Local graphs keep working. Check the connection; for Managed Sync, open Sync settings and Continue to secure sign in; for a custom server, check the token has not expired or been revoked at the portal (Managed Sync Or Your Own Server).

"Uploading to the storage bucket was blocked"

The server's storage bucket is not configured to accept requests from the app's address. Notes keep syncing; only images and files are affected. It is a one-time CORS setting for whoever runs the server (Self Hosting The Sync Server).

"You have reached your plan's storage allowance" or another limit

A write on the managed service would pass one of the plan's limits. The edit is kept on the device and retried once there is room. Delete unused graphs, images or files, or move to a larger plan on the Billing page (Your EtherPK Account).

Graphs I own have become read-only

The Sync+ subscription has ended. You can still read, mirror and delete the graphs you own, and they are deleted from the managed service after a retention period. Restart Sync+ from Billing to write again, or keep a Local Mirror of anything you want (Your EtherPK Account).

A backlink, task or search result is missing or wrong

The index that Search, Backlinks and the Tasks view read has fallen behind. Open Settings > Maintenance and select Rebuild search index. Your documents are not changed. Remember that a protected document is never indexed, so its contents never appear in any of the three (Protected Documents).

Search finds nothing while the graph is opening

Text results are withheld until the index has finished building after a large graph opens, so a search can never wrongly say "not found". Names are searchable straight away. Wait for the progress line under the results to finish (Search).

"Frontmatter kept." at the foot of the page

You pressed Backspace or Delete at the edge of the frontmatter block, which would have joined body text onto the closing --- and turned the block into ordinary text. The edit was refused. Edit inside the block, or select the whole block to delete it (Titles Aliases And Frontmatter).

"That task has moved since it was indexed"

You ticked a task in the Tasks view, but the line in the document no longer holds that task, usually because it was edited or moved a moment ago. Nothing was written; the document opens at the task so you can tick it there (Tasks).

"etherpk/protection.json is damaged"

The file holding a local graph's wrapped protection key has been corrupted, by a merge conflict, a cut-short copy or a full disk. EtherPK refuses to touch it. Restore it from a backup or the other side of the merge; the encrypted documents are untouched and open again once it is back (Protected Documents).

A protected document's contents vanish when I switch windows

By design. The contents are hidden the instant the window loses your attention and come back without a passphrase within the grace period. After the lock timer they need the passphrase or a passkey. Both timings are under Settings > Protected Documents.

Alt+Shift+P opens Settings instead of publishing

The shortcut publishes without a dialog only when it can tell which publication and where: the one last published from this device (or the graph's only one), into a folder already chosen. Publish once from the Publish tab with Choose folder… and Publish to folder; the shortcut follows that from then on. A zip download does not count as a folder (Publishing Your Notes As A Website).

"EtherPK was not allowed to write to the folder" when publishing

The browser needs the folder permission granted again after a restart, and grants it only from a click. Select Choose folder… and pick the same folder.

Diagrams are left as text on a published site

Mermaid needs a browser to lay out text, so only a publish run from the Client draws them. A diagram whose source Mermaid rejects is also left as text, with the message in the report. An agent publishing through the Headless Client needs diagrams setup run once (The Headless Client).

A page is missing from a published site

The publish report (Show report on the finished notification, or under the publication in Settings > Publish) says which documents were left out and why: not public, not naming the publication, protected, or used as an include (Publishing Your Notes As A Website).

The mirror dot is red

Mirroring has stopped and needs you, most often because the browser dropped the folder permission after a restart. Select the dot to open the Mirror tab and grant access again, or choose the folder again (Keeping A Local Copy Of A Synced Graph).

The Headless Client says "chromium_unavailable" or refuses to search by meaning

The agent's computer has not had the one-off setup: npx @appsoftwareltd/etherpk-mcp diagrams setup for publishing diagrams, semantic setup for searching by meaning. Each message names the command. On NixOS set ETHERPK_CHROMIUM to the system Chromium instead (The Headless Client).

Claude Code shows "Connection closed" for etherpk

The Headless Client exited at start. Run the same serve command by hand in a terminal to see why: usually the computer is not signed in to that server (login again), the graph id is wrong (graphs lists them), or an old version needs upgrading.