Troubleshooting
The connection card says "Can't reach aether-mcp"
The server is not running, or the URL is wrong.
- Run
aether-mcp service status, or start it in the foreground with the command in Install aether-mcp. - Confirm Aether control-plane URL matches the server's
--http-addr. The default ishttp://127.0.0.1:14771. - The status bar shows
Aether: Offlinein this state. Your notes are untouched. Start the server and run Sync vault with Aether to recover.
The connection card says "The server rejected the API key"
The server was started with --require-auth.
Paste a valid aek_... token into API key.
The key needs the Reader role or higher.
The server refuses to start on a non-loopback address
Without --require-auth, the server accepts only 127.0.0.1 and ::1.
Add --require-auth and a key, or bind to loopback.
AMC also rejects plain http:// URLs for non-loopback hosts and any remote host without an API key.
aether-mcp setup says it needs an interactive terminal
setup asks questions, so it needs a terminal.
Run it in a terminal, or pass --yes to accept the defaults, and --vault <path> to name the vault.
NO_COLOR and TERM=dumb also turn the prompts off, so use --yes in those cases too.
setup says no Obsidian vault was found
setup reads the vault list from Obsidian's own configuration, so a vault that Obsidian has never opened is not listed.
Pass --vault /path/to/vault.
aether-mcp rejects a flag with a usage message
Unknown flags and invalid values are errors, with exit code 2, instead of being ignored.
Run aether-mcp --help for the accepted flags.
npx @muninn-org/aether-mcp cannot download the binary
The launcher downloads the release from GitHub, so it needs network access to github.com.
If the message says the release may not include a build for your machine, your platform is not in the supported list.
Set AETHER_MCP_DOWNLOAD_BASE to use a mirror, or install with the installer script instead.
It also needs tar on your PATH to unpack the download.
A Docker container exits immediately
Keep --http-only in the arguments.
Without it the stdio loop ends in a detached container and stops the server.
Run Dream consolidation on push fails with HTTP 403
On an authenticated server, this needs an Admin key.
Turn off Run Dream consolidation on push, or use an Admin key.
Edits right after opening Obsidian do not sync
AMC starts watching for edits after Obsidian finishes loading, so the initial load does not flood the server. Edit the note again, or run Sync vault with Aether.
The agent cannot find a note
- Check the note's frontmatter.
aether_tier: private,.aetherignore, and the built-in exclusions all hide notes from agents. - With a scoped key, the agent sees only notes in its scopes plus
global. - Run Sync vault with Aether, then check the notice for updated and indexed counts.
- Run
aether-mcp doctor --vault /path/to/vaultto check the vault and client configuration.
A proposed memory never appears in the inbox
Run Sync vault with Aether, or set Auto-pull interval (seconds) to a positive number. The inbox pane shows what the server has staged.