Troubleshooting

Problems are grouped by the part of EtherPK they come from. Most entries take their heading from a message the app shows, with "…" in place of a name it fills in. The message appears in a notice, a dialog, the sync status at the foot of the Graph Sidebar, the account button in the header or the Graphs page. It can also replace a graph that cannot open.

A local graph is a folder on your computer that the browser can reach with your permission. A synced graph is encrypted on your device with your Encryption Keys and stored on Managed Sync, and its owner can share it with other people, who join as Players (see Sharing A Graph). If something fails, a local graph keeps your edits in the open tab until EtherPK writes the file, and a synced graph keeps them on this device until the Sync Server accepts them. Until then, do not close the tab or clear the browser's site data.

On this page, the Sync Server always means Managed Sync's. For a problem not listed here, or one that only EtherPK can clear, see Other problems.

Local graphs

"EtherPK needs permission to read and write this graph's folder"

On a computer, Chrome and Edge do not keep the folder permission between visits, but EtherPK installed as an app does. Select Grant access and allow it when the browser asks.

See Local Graphs for more information.

No "Open folder (Local Graph)" button

The Graphs page shows Open folder (Local Graph) only in a browser that can open a folder: Chrome or Edge on a computer, or Chrome on Android. Synced graphs work in any browser.

See Choosing Where To Store Your Notes and Running EtherPK On Your Own Computer for more information.

"Could not save …"

EtherPK could not write a document to its file, and the notice says why. Until a save succeeds, your edits exist only in the tab, so closing the tab loses them. Fix the cause, then select Retry saving.

On Windows, "Another program was using the file at the same time" means something such as a virus scanner or the Headless Client had the file open, and Retry saving usually works.

See Local Graphs for more information.

"External change"

The file changed on disk while its tab had unsaved edits. EtherPK does not merge the two versions, so you keep one and lose the other. Select Keep mine to write your version over the file, or Take disk to load the version on disk and drop your edits. The dialog stays open until you choose.

See Local Graphs for more information.

Synced graphs and sharing

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

This browser has no record of the graph. Your notes are stored on the Sync Server, so nothing is deleted. Select Set it up here and they sync down as usual.

See Where Your Data Is Stored for more information.

"Sign in to open this graph"

You are signed out of EtherPK in this browser, but your notes are still on the Sync Server and nothing is deleted. Select Sign in to get back to the graph.

See Your EtherPK Account for more information.

"You no longer have access to this graph"

The owner deleted the graph, or you left it or were removed. This browser still has a copy, and changes in it that never reached the server are lost when you remove it. So select Download unsent changes before you delete the copy with Remove from this device.

See Sharing A Graph for more information.

"Waiting for key"

This device does not have the graph's new key yet. Your edits stay on this device until the key arrives, and then they sync. The sync status says why the key has not arrived and who can fix it.

See Sharing A Graph for more information.

"Your Encryption Keys were replaced or reset on another device"

The Encryption Keys unlocked on this device no longer open your account's data, so you need to unlock them here again. Select Unlock Encryption Keys on the Sync tab of the Graphs page, then approve this device from another unlocked device or use the new Recovery Code.

See Recovery Code And Device Approval for more information.

"… publishes a security key that is not yours"

The Sync Server is publishing a security key for your account that does not match your Encryption Keys, and it refused to publish yours. Invites sent to you could be sealed to that key, so do not send or accept any until the problem is cleared. Only EtherPK, which runs Managed Sync, can clear it, so report it to EtherPK support through Help And Community.

"…’s security key has changed" or "Key changed"

This person's key on the Sync Server is not the one you compared before. They might have replaced their Encryption Keys, or someone might be trying to read what you share. Since either could be true, an invite to them waits and a graph you own keeps its old key until you compare fingerprints again, in person or over a call you trust. If the fingerprints match, select It matches, trust the new key.

See Sharing A Graph for more information.

"This version of EtherPK is too old for this Sync Server"

The Sync Server refused a request from an older version of EtherPK or the Headless Client. Reload the page, or update the Headless Client.

See The Headless Client for more information.

"Sync unavailable"

The account button in the header shows this when the Sync Server does not answer. Local graphs keep working, and in an open synced graph your edits stay on this device until the server answers. To check again, select Try again on the Graphs page.

See Synced Graphs for more information.

"Enter this device's passcode"

Your device passcode protects the Encryption Keys on this device, and they stay encrypted until you enter it. Synced graphs wait for the passcode after every EtherPK tab has closed or the only open tab has reloaded. Enter it in the dialog.

See Device Passcode for more information.

"… could not be shown because it arrived incomplete"

A file in a synced graph did not match the record made at upload. EtherPK does not show or save it, so no damaged copy ends up in an export or on a published site. Select Retry.

See Images And Files for more information.

"Changes are not reaching the sync server"

The graph owner's plan does not allow changes to this graph, and the sync status shows "Not syncing" with the reason. Your changes stay on this device and go through on their own once the server accepts them, so you do not need to retype anything. Only the owner can fix the plan, with Restart Sync+, Fix payment or Open Billing, so a Player has to wait.

See Your EtherPK Account and Sharing A Graph for more information.

"… so the graphs you own are read-only"

The Sync tab of the Graphs page shows this when your Sync+ subscription has ended or a payment is overdue. You can still open, export and delete the graphs you own, and Restart Sync+ or Fix payment makes them writable again. Once Sync+ has ended, Managed Sync deletes your graphs when a retention period runs out, so export or mirror anything you want to keep.

See Your EtherPK Account for more information.

Phones

"Your browser cleared some of EtherPK's data on this device"

EtherPK has restored the list of synced graphs and the passkeys for protected documents, and documents download again the next time you open a graph. Edits that had not reached the Sync Server cannot be restored. Installing EtherPK as an app makes a repeat less likely.

See Where Your Data Is Stored and Installing EtherPK As An App for more information.

EtherPK is missing from the share sheet

EtherPK appears in the share sheet only when it is installed on Android (from Chrome) or on ChromeOS.

See Installing EtherPK As An App and Quick Notes for more information.

Pages, search and links

"… was renamed to … outside EtherPK" or "… was renamed to … elsewhere"

Another program or an agent changed title: in the page's file, or a synced document was renamed on another device. The open tab follows the new name, but links to the old name stay as they were, because the rename had already happened by the time EtherPK saw it. To make those links work again, add the old name under aliases:. Next time, use Rename… in EtherPK, which updates links.

See Titles Aliases And Frontmatter for more information.

"Frontmatter kept"

EtherPK refused an edit that would have turned the frontmatter block into ordinary text, and left the document unchanged. Edit inside the block or below it. To end the block on purpose, delete the dashes on a --- line, and to delete the whole block, select all of it first.

See Titles Aliases And Frontmatter for more information.

Missing or wrong backlinks, tasks or search results

Search, Backlinks and the Tasks view read the same search index, so one rebuild fixes all three. Select Rebuild search index in Settings > Maintenance. It re-reads every document and changes none.

See Search for more information.

"Duplicate names"

Two or more documents in a synced graph have the same name, which happens when more than one device made the page before they synced. The name opens only one of them, so the text in the others is hidden, and Search can find text that no open document shows. Instead of rebuilding the index, select Review, then in Settings > Maintenance, under Duplicate names, select Merge….

See Graph Settings for more information.

"Still indexing this graph"

Just after a graph opens, Search holds back text results until the index is built, so it cannot wrongly report that nothing was found.

See Search for more information.

Tasks and boards

"That task changed after the list was read"

You ticked a task whose text has changed since the list was read, or whose text now appears on more than one task. Because the Tasks view finds a task by its words, it refused the tick, wrote nothing and opened the document at the task instead.

See The Tasks View for more information.

"… was renamed or deleted after the list was read"

The task's document was renamed or deleted after the Tasks view read the list, and nothing was ticked. To reload the list, select the refresh button at its top right.

See The Tasks View for more information.

"… changed after the board showed it, so it was not moved"

The task on this card changed after the board showed it, or its text now appears on more than one task. A Kanban board finds a task by its words, so it wrote nothing and put the card back where it was. Move it again.

See Kanban Boards for more information.

"… has changed since it was moved, so the move was not undone"

On a board, Ctrl+Z (Cmd+Z on a Mac) undoes a move only while the task's line still says what the move wrote, so it never loses an edit made since. Move the card again, or edit the line in its document.

See Kanban Boards for more information.

"Could not find the task the address names" or "Could not tell which task the address names"

A task reference opens the task's document and finds the task by its words, so editing those words or deleting the task breaks the reference. If more than one task has the same words, EtherPK does not guess. Find the task yourself, change its words if another task shares them, and copy a new instruction with Copy agent instruction.

See Tasks for more information.

Protected documents

"etherpk/protection.json is damaged"

In a local graph, EtherPK keeps your protection key in etherpk/protection.json and never writes over a damaged copy, so your encrypted documents stay as they were. Restore the file from a backup or from the other side of a merge, and the documents open again.

See Protected Documents for more information.

Protected text disappears when you switch away

Protected text is hidden as soon as you switch away, whatever your settings. The Lock after I switch away setting in Settings > Protected Documents controls only how long you can be away before you need your passphrase again.

See Protected Documents for more information.

Publishing

Alt+Shift+P opens the Publish tab

Alt+Shift+P publishes without a dialog only when EtherPK knows the publication (the last one published from this device, or the only one) and a destination is chosen for it on this device. Otherwise the key opens the Publish tab, which shows the message "No folder or repository is chosen for … on this device" if only the destination is missing. Publish once from the Publish tab first.

See Publish Settings for more information.

"EtherPK was not allowed to write to the folder"

EtherPK no longer has permission to write to the publication's folder. On the Publish tab, select Change folder… and choose the same folder.

See Publish Settings for more information.

Diagrams left as text on a published site

When Mermaid cannot read a diagram, the site shows the diagram's source text and the publish report gives Mermaid's message. Fix the source and publish again. The Headless Client will not publish a site with diagrams or maps until diagrams setup has run.

See Code Maths And Diagrams for more information.

A page is missing from a published site

The publish report lists each document it left out and why: not public, not in the publication, protected, a publication page, or used as an include. Open it with Show report when a publish finishes, or find it under the publication in Settings > Publish for as long as the graph stays open in this tab.

See Publish Settings for more information.

Local Mirror and export

"Mirroring to … has stopped"

A red dot in the toolbar means the Local Mirror has stopped and is waiting for you. The mirror stops when it loses permission to write to its folder, when the folder is gone, or when writes keep failing. Select the dot to open Mirror and Export, then select Reconnect and carry on or Choose the folder again….

See Keeping A Local Copy Of A Synced Graph for more information.

"This graph's attachments come to about …"

In a browser that cannot save straight to a file, EtherPK builds the export archive in browser storage first, and that storage does not have enough free space. Export from Chrome or Edge on a computer instead, or free some browser storage.

See Keeping A Local Copy Of A Synced Graph for more information.

"An earlier export's download file is still on this device"

EtherPK removes the download file from an earlier export an hour after the download began. To remove it sooner, select Remove it in Settings > Mirror and Export.

See Keeping A Local Copy Of A Synced Graph for more information.

AI agents

"chromium_unavailable" or "Semantic search is not set up"

Publishing diagrams and maps needs a one-off setup on the computer that runs the Headless Client, and so does searching by meaning. Run the command the message names:

npx @appsoftwareltd/etherpk-mcp diagrams setup
npx @appsoftwareltd/etherpk-mcp semantic setup

See The Headless Client for more information.

"Connection closed" in Claude Code

The Headless Client exited while it was starting. Run the same serve command in a terminal to see why.

See The Headless Client for more information.

"… did not accept the token"

The Sync Server refused the agent token, perhaps because it was revoked, mistyped or left unused for 30 days. Create an Agent Setup Code on the Agents tab of the Graphs page, or in Settings > Agents in a synced graph, then run login again.

See The Headless Client for more information.

"Encryption Keys unlocked and kept in … (owner-only)"

login kept the agent token and your Encryption Keys in a file that only your user account can read. It uses the system keychain only when it can save them there and read the same values back, and never on Windows or when ETHERPK_MCP_SECRETS is set to file. On Linux, the keychain needs secret-tool (the libsecret-tools package on Debian and Ubuntu) and a desktop session. If secret-tool is missing, install it and run login again.

See The Headless Client for more information.

Other problems

See Help And Community for the Discord community, email support, and where to report a bug or a security problem.