Troubleshooting

Common errors and how to fix them.

"macOS is asking for permission to use the keychain"

macOS showed a keychain permission dialog and nobody answered within 20 seconds, which happens on a locked screen or an unattended Mac. Allow it at the machine and run the command again. On a machine nobody sits at, run aisync keystore file to keep keys in a 0600 file. The choice is saved in aisync's config, so it also applies when Claude Code starts MCP servers without your shell environment. Run aisync unlock (and aisync vault login for Vault) again after switching.

"secrets for … are locked on this machine"

This machine has no key for the store: it's a new machine, or the passphrase was changed elsewhere with aisync passwd.

aisync unlock

An MCP server doesn't start

Run the server's command from .claude.json in a terminal to see the error:

aisync exec --repo you/aisync-config -- npx -y @modelcontextprotocol/server-slack

Usually the key is missing (see above), the referenced token name isn't in the store, or the Vault token expired.

"profile … changed in the repo since your last pull"

Another machine pushed the same profile. Pull first; files you changed only here stay.

aisync pull default
aisync push default

"these changed both here and in the repo"

Both sides changed the same file. aisync pull --force takes the repo's version, aisync push --force keeps yours. See Syncing and conflicts.

"secret-looking values would be committed in plain text"

What you're uploading contains a token. For an MCP server, add --secrets to move it to the store; for a file, take the value out. Secrets explains how.

A new MCP server doesn't show up after a pull

Claude Code reads MCP servers only when a session starts. Restart the session.

Worried a first pull will wipe your setup

aisync pull default --dry-run shows what would change. A real pull also copies every file it changes or removes to <config folder>/.aisync/backup/ first.

These docs describe aisync 0.1.