Troubleshooting

hydrate doctor reports "License: Free" after I paid

Cause: registration succeeded against the licensing service but the resulting key wasn't written to ~/.hydrate/license.json. Usually a permissions issue on first run, or the previous CLI version crashed mid-activation.

Fix: re-run activation locally.

hydrate register --edition=pro --email=<your-email>

The command is idempotent: it re-fetches your signed key and writes it. Then run hydrate doctor again; the Licence line should flip to Pro.

hydrate register says "Could not resolve host: licensing.gethydrate.dev"

Cause: known v0.4.0 bug. The binary points at a hostname we never deployed. The real licensing service is at license.gethydrate.dev (no licensing prefix).

Fix: upgrade to v0.4.2+ where the endpoint is corrected.

brew upgrade hydrate

See /docs/upgrading for verifying after the upgrade.

Hooks not firing in Claude Code

Cause: one of three things. Walk them in order.

1. Missing hook entry. ~/.claude/settings.json doesn't list UserPromptSubmit (or the others). Reinstall the hook block:

   hydrate install-hooks

2. Hooks installed but binaries missing from PATH. The hook entries reference claude-context / claude-capture by name. If ~/.local/bin (or /opt/homebrew/bin) isn't on PATH, the hooks no-op silently.

   which claude-context claude-capture hydrate-server hydrate-mcp

   All four should resolve. If not, re-link the bin directory or reinstall.
3. Two claude binaries on PATH. A common gotcha when Claude Code was installed both via npm i -g @anthropic/claude-code and via brew. They read different settings paths. Confirm which one is actually running:

   which claude
   claude --version

   Then make sure the matching settings.json has the Hydrate hook entries.

hydrate-server won't start

Cause: port collision, permission, or migration error.

• Port already in use, usually a stale hydrate-server from a crashed Claude Code session.

  hydrate server stop
  hydrate server start

• Permission error on ~/.hydrate/, often because the data dir was created by a different user (typically during a sudo install).

  chmod 700 ~/.hydrate
  chown -R "$(id -un)" ~/.hydrate

• Migration error on upgrade: the server is trying to apply a schema migration and failing. hydrate doctor prints the exact migration error verbatim.

  hydrate doctor

  Most migration errors resolve by re-running hydrate server start after the doctor output points at the offending row.

MCP server not connecting in Cursor / Cline / Zed

Cause: the client's MCP config file doesn't list hydrate-mcp as a server entry. Hydrate writes the entry for Claude Code automatically but not for third-party clients.

Fix: for Claude Code, re-run hydrate install-hooks. It writes the entry into ~/.claude.json. For other clients, copy the entry from the docs.

hydrate install-hooks   # Claude Code only

For Cursor, Cline, Zed, and Gemini CLI see /docs/integrations; each has a 3-line config snippet you paste into the client's MCP config file.

hydrate dehydrate not finding facts

Cause: the source file (usually CLAUDE.md) doesn't contain the expected fact markers. Dehydrate scans for explicit [FACT: ...] blocks, not free-form prose.

Fix: see /docs/dehydrate for the marker format. The short version:

[FACT: API base is /api/v2, never /api/v1]
[FACT: auth uses Ed25519 signed tokens, never bearer]

Once marked, hydrate dehydrate ./CLAUDE.md ingests them into the fact store and rewrites the source file with the facts elided.

Slow claude-context hook on session start

Cause: the hook is calling out to siteengine_ai (the upstream context-extraction service) and timing out on a slow or restricted network.

Fix: hooks are fail-safe (they no-op rather than block the prompt), but the timeout still adds latency. Short-circuit the network call:

export HYDRATE_OFFLINE=1

Add it to ~/.zshrc / ~/.bashrc if you're behind a corporate proxy or working air-gapped. Local fact retrieval still works; only the optional remote enrichment is disabled.