Troubleshooting

Start with status

synapse version
synapse path
synapse data check
synapse status .
synapse settings show

These commands establish which executable is running, which database it opens, whether the database is healthy, which scopes apply to the current folder, and which response budget connected tools use.

One command for a bug report

synapse doctor gathers everything anyone would ask you for: version, store state and size, which tools are connected and what each is set up with, skill and mesh state, shell and CLI integration, resolved paths, and any crash Synapse has recorded.

synapse doctor
synapse doctor --json

Every check reports rather than fails, so a damaged store is described in the report instead of ending it. Synapse sends nothing anywhere — the report is printed for you to read or paste.

App and CLI

macOS will not open the app

Confirm you downloaded the current archive from the release page, extracted it fully, and moved the app to Applications. The app is Developer ID signed and notarized, so a Gatekeeper refusal usually means the archive was altered or only partly extracted. Avoid modifying files inside the application bundle because that invalidates its signature.

synapse: command not found

Install the CLI from Settings, then add ~/.local/bin to PATH. Run the executable by full path once to verify:

~/.local/bin/synapse version

The CLI installer reports a conflict

A different file already exists at the destination and does not have a matching Synapse receipt. Synapse will not replace it. Move or rename that file yourself, or set SYNAPSE_BIN to a different full destination and install again.

The CLI stopped working after moving the app

Packaged installations point into the signed bundle. Open Synapse at its final location and choose Install CLI again to refresh the managed launcher.

Tool connection

A tool is detected but not connected

The registered entry may point to a deleted build or old app location, or may have arguments other than ["mcp"]. Choose Repair in the app. Synapse backs up the integration store before replacing the named entry.

The tools do not appear after connection

Restart the developer tool so it relaunches user-level MCP servers. Confirm the stored command exists and runs synapse mcp without printing shell startup text to stdout.

The tools follow different global guidance

Run synapse guidance show. If a pointer is missing, use synapse guidance sync or Settings → Shared guidance → Sync pointers, then restart the tools. Consolidation is optional and requires separate confirmation.

Setup failed

Read the app error for the external tool command that failed. Setup restores both the integration store and instruction file on failure, leaving .synapsebackup recovery copies beside changed existing files.

Scopes and secrets

vault scope is not ready

Run synapse status .. Approve pending or changed files with synapse allow only after inspecting them. Fix invalid YAML and unknown vault.name references before trying either shell mode again.

The shell hook does not activate

Open Settings and check Shell environments. Enable or repair the detected hook, then open a new terminal. Run synapse status .; it should report the current shell hook and ambient state as ready. Approve the closest scope with synapse allow. Global mappings alone never activate ambient mode.

Settings reports an incomplete or duplicate hook block

Synapse refuses to guess which startup-file content it owns. Open the path shown in Settings, reduce the # synapse:shell:begin and # synapse:shell:end markers to one complete pair or remove that marked block, then return to Settings and enable the hook again.

An ambient value remains after leaving

Press Enter once so the prompt hook reevaluates the directory. If the name existed before activation, Synapse deliberately restores that original value. Run synapse status . to distinguish a restored value from an active scope.

A narrower mapping does not apply

Check every ancestor scope. A broader deny permanently blocks that environment name for narrower scopes. Also confirm the nested file itself is approved and the command’s working directory is below it.

Keychain access fails

This applies on the Keychain store only; run synapse vault backend to see which one this machine uses. Unlock the login Keychain and retry from an interactive user session. If a label exists but its item was removed externally, set the secret again. If the credential itself may be invalid, rotate it at its issuer before storing the replacement. A denied Keychain prompt during vault migrate stops the migration with nothing moved and nothing switched, so retrying after granting access is safe.

A secret has no value in the encrypted vault

The label is in brain.db and the sealed value is not in vault.db. That happens when the two came from different machines, or when a value was set while the machine was on the other store. Run synapse vault backend to confirm which store is in use, synapse vault migrate to bring values across from the other one, or synapse secret set to write the value again.

Nothing opens with the vault key

vault.key is the only thing that opens vault.db, and a replaced key cannot be recovered from the sealed values. If the key was lost, set each value again with synapse secret set; the labels and mappings in brain.db tell you which ones are expected. Back the two files up together, and treat that backup like the credentials it holds.

The child sees a value but MCP does not

This is expected. MCP reports only names, trust state, and which store this machine uses. Values are read out of the vault only for synapse run -- <command>, while an installed shell hook activates an approved directory, or when you ask for one with synapse secret copy.

Memory and database

Recall returns too little content

Run synapse settings show. Switch to Balanced or Full if Lean is too small. Search with concrete words present in the stored body and inspect the exact entry through synapse memory show <id>.

A memory that is definitely stored does not come back

Make the search show its working with synapse memory list "your query" --explain. It prints the words it searched for and the words it dropped for matching nearly every memory, which separates a query that lost its only real term from a store that holds nothing. If what you are looking for is an exact string — a flag, an identifier, a path — use synapse memory grep instead, which matches characters and never drops a word. Also check the entry has not been superseded: synapse memory list marks a replaced memory, synapse memory show <id> names what replaced it, and synapse memory restore <id> puts it back in recall.

A stored memory is wrong

If the wording was bad, edit the original. If it was true and stopped being true, add the new version and run synapse memory supersede <old> <new> — recall returns the new one and the old text stays readable. If it should never have been stored, delete it. What to avoid is adding a contradictory entry and leaving both live, because recall returns both. Export a snapshot before a large cleanup.

An import shows flagged entries

Open the provider folder with Review source and inspect the named files. The app never imports flagged content. If a CLI import is genuinely safe, rerun it with both --include-flagged and --confirm; otherwise move only the durable non-sensitive fact into Synapse manually.

One project's memory appears missing

Inspect the record's project root in the Memory editor and compare it with the current repository root. Project recall intentionally combines global memory with one matching project and excludes every other project.

Integrity check fails

Stop using the affected database. Do not overwrite it. Preserve the whole data directory, locate the newest known-good export or automatic backup, and follow the restore procedure. A failed check is a data-recovery event, not a migration prompt.

Restore

Restore says Synapse is using the database

Quit the desktop app and close every developer-tool session connected to the MCP server. Confirm no synapse mcp process remains, then retry. The refusal proves the exclusive lifecycle guard is working.

The backup version is unsupported

The source schema must match the current release. Keep the source unchanged. Open it first with the Synapse version that created it, let that version migrate normally if appropriate, export a fresh snapshot, then restore that compatible export with the current app.

Secrets are missing after moving to another machine

Database exports carry brain.db and never a value. Recreate each value with synapse secret set on the destination, or — on the encrypted store — copy vault.db and vault.key across together, since neither is any use without the other. Existing vault labels and references in the restored database tell you which entries are expected.