Troubleshooting

This page collects the most common problems and their solutions. For each symptom it gives the likely cause and the steps to resolve it.

Authentication failed / invalid token

Symptom: the connection to the repository fails with an authentication error; the dashboard shows Connection failed or a message about invalid credentials.

Cause: the personal access token (PAT) has expired, been revoked, or lacks the required permissions.

Fix:

1. On your git provider (GitHub, GitLab, Gitea, Azure DevOps…), generate a new PAT with read and write permissions on the repository.
2. To update credentials only (without changing the URL), click the circular button with your initials at the top right of the dashboard to open User settings, then update the username and token in the Sync credentials section and click Verify & save. Available to every role.
3. If you also need to change the repository URL, go to the System tab → Change repo instead (requires the Maintainer role).
4. Reload VS Code if prompted.

For a full guide to the credentials panel, see User settings.

”Changes pending upload” / “To send ↑N” status

Symptom: the top bar of the dashboard shows Changes pending upload (or To send ↑N) persistently, even after repeated syncs.

Cause: there are local commits not yet pushed to the remote repository.

Fix:

1. Click Sync now: the engine pulls before pushing.
2. If it persists, open the System tab → Show log: any real conflict is reported there (never resolved behind the scenes). Also check your network connectivity and that the token is still valid.
3. As a last resort, use Reset in the System tab to re-clone the local clone.

Note

On a machine with the member role (read-only on CORE), the status normalizes on its own after the next cycle: the member doesn’t author the shared configuration.

Can two machines overwrite each other?

Symptom: a worry that one machine, when syncing, deletes the work done on another.

Cause: a legitimate concern when multiple machines share the same repository.

Fix: it can’t happen. There’s no force-push. When machines diverge, the tool additively reconciles what it can merge — the memories and shared accumulative files — and surfaces the rest in the dashboard for a human decision. Nothing is overwritten silently.

Note

KoNiMa Claude Sync never performs a force-push. Conflicts are shown in the dashboard and never resolved by overwriting someone else’s work.

Push rejected

Symptom: the sync starts but ends with an error; the log shows push rejected or non-fast-forward update.

Cause: the remote repository has received commits from another machine that aren’t yet integrated locally, or the local history has diverged.

Fix:

1. Click Sync now from the dashboard — the engine pulls before pushing.
2. If the error persists, open the System tab → Reset to clear and re-clone the local clone (safe: the source of truth is always ~/.claude).
3. If the history is bulky, use Compact history to bring it back to a clean state (the old history stays reachable through a recovery ref).

Memories not syncing

Symptom: project memories don’t appear on a machine, or local observations aren’t being pushed to the repository.

Cause: one of these — (a) claude-mem isn’t installed, (b) the memory sync switches are off, (c) the edition doesn’t include memories (available only in Pro and Team).

Fix:

1. Open the dashboard, Memory tab.
2. If the claude-mem not installed section appears, copy the install command (claude plugin install claude-mem@thedotmack) and run it in a terminal.
3. Confirm that the Sync claude-mem memories (database) and Sync project .md memories switches are on.
4. If the Memory tab isn’t present, your edition doesn’t include memories — consider upgrading to Pro or Team.
5. Click Sync now to force a full cycle.

The same project is in different folders on two machines

Symptom: the same project is cloned at different local paths on different machines, and you wonder whether the memories will still be associated correctly.

Cause: this is an expected case: the local path can change from machine to machine.

Fix: there’s nothing to do. The project is identified by its git remote and the memory is remapped onto each machine’s local folder. The remapping is visible in the Projects tab, where each project shows the machine → local path list.

Caution

A project without a git remote can’t travel between machines, because it lacks an identity. These projects are listed separately as Unmapped projects in the Projects tab.

If the same project ever appears duplicated (for example after registering it under different names), the System tab offers Re-align projects and memories: it reunites the memories under a single entry, so that each project appears only once. It’s safe to run at any time and is also launched automatically after each sync.

Re-align projects and memories: useful if the same project appears more than once.

Sync “won’t start” / passive state

Symptom: the status bar shows the passive state (no colored indicator) and sync doesn’t happen, even after pressing Sync now.

Cause: another VS Code window on the same computer owns the sync engine. With multiple VS Code windows open, only one drives the sync; the others follow in passive mode. This is normal behavior.

Fix:

1. Find the other open VS Code window (even in the background) and use it to start the sync, or close it.
2. Once the extra windows are closed, the engine is automatically acquired by the remaining window.
3. If in doubt, use System check in the System tab for a full diagnostic of the environment.

The System check verifies the environment and reports what works and what doesn’t (the values shown are examples).

Seat limit reached

Symptom: when trying to activate the extension on a new machine, Machine limit reached appears or the machine isn’t registered.

Cause: the number of active machines has reached your edition’s limit.

Fix:

1. Open the dashboard on an already-active machine, Machines tab.
2. Identify the unused or idle machines (the interface flags those idle for 30+ days).
3. Click Deactivate on the machine to release (in the Team edition you need the Maintainer role).
4. Go back to the new machine and repeat the activation.

Alternatively, consider upgrading to an edition with more or unlimited seats.

MCP credentials missing after sync

Symptom: after a pull on a new machine, the MCP servers appear in the configuration but don’t work; Claude Code reports missing or invalid credentials.

Cause: MCP server credentials are removed before the push (scrubbing) for security. Only the server’s structure (URL, name, arguments) travels in the repository.

Fix:

1. Open VS Code on the new machine and go to the MCP settings (or the configuration file the app points to).
2. Re-enter the credentials (token, API key…) for each MCP server that requires them.
3. The credentials go into the VS Code secret store — you don’t need to repeat them on every future sync on this machine.

Commands or actions that stay pending

Symptom: a dashboard action button shows a spinner and seems “stuck”.

Cause: every button is disabled with a spinner until the operation responds. This is the expected behavior, not a freeze.

Fix: wait for the operation to complete. Don’t click again: re-launching the same action won’t speed it up.