Troubleshooting

Node version error on install

SwarmVault requires Node >=24. If you see an engine compatibility error:

node --version     # check current version

Upgrade with your preferred version manager:

nvm install 24
nvm use 24

Then reinstall:

npm install -g @swarmvaultai/cli

node:sqlite experimental warning

Current SwarmVault releases suppress the upstream node:sqlite experimental warning during normal CLI runs.

If you still see:

ExperimentalWarning: SQLite is an experimental feature...

you are usually running an older CLI version or a source checkout that has not been rebuilt yet. Check your version and upgrade or rebuild:

swarmvault --version
npm install -g @swarmvaultai/cli@latest

Heuristic provider output quality is low

The built-in heuristic provider is a valid local/offline default. It does not call an external model, so its synthesis is intentionally lighter.

If you want richer synthesis quality or optional capabilities such as embeddings, vision, or image generation, configure a model provider in swarmvault.config.json:

{
  "providers": {
    "primary": {
      "type": "openai",
      "model": "gpt-4o",
      "apiKeyEnv": "OPENAI_API_KEY"
    }
  },
  "tasks": {
    "compileProvider": "primary",
    "queryProvider": "primary"
  }
}

See Providers for all supported options.

How to update SwarmVault

Check your current version and upgrade:

swarmvault --version
npm install -g @swarmvaultai/cli@latest

The CLI also prints an upgrade notice when a newer version is available during interactive use.

Compile seems slow

SwarmVault compiles incrementally by default. Only sources with changed content hashes are reprocessed. If compile feels slow:

• Check which sources changed with swarmvault lint (stale pages indicate what needs recompilation)
• Reduce the source set with --include and --exclude globs during ingest
• Use the heuristic provider for a fast local structural pass, then optionally switch to a model provider for richer compile output

Current releases also bound source-analysis concurrency and graph projection during compile. If an older CLI fails on a large note set with heap exhaustion or Map maximum size exceeded, update SwarmVault and rerun swarmvault compile.

If compile reports Failed to parse JSON file ..., the named derived state file is corrupt or empty. Remove the named file or restore it from git, then rerun swarmvault compile; current releases write JSON state atomically to reduce partial-file failures.

Graph query returns no results

The graph must be populated before queries work:

1. Run swarmvault compile at least once to build state/graph.json
2. For semantic graph queries, configure an embeddingProvider in tasks:

{
  "providers": {
    "ollama-embeddings": {
      "type": "ollama",
      "model": "nomic-embed-text",
      "baseUrl": "http://localhost:11434/v1"
    }
  },
  "tasks": {
    "embeddingProvider": "ollama-embeddings"
  }
}

Without an embedding provider, graph query uses lexical matching with group-pattern fallback, which may miss semantic matches. The built-in heuristic provider does not generate embeddings, so point embeddingProvider at Ollama or another embedding-capable backend.

Watch mode is not detecting changes

Make sure you are watching the right paths:

swarmvault watch status       # shows watched repo roots and pending changes
swarmvault watch --repo       # explicitly include tracked repos

For git-integrated workflows, install hooks instead:

swarmvault hook install       # triggers refresh on commit and checkout

Graph seems stale

Check freshness first, then refresh only what changed:

swarmvault graph status .                      # read-only freshness check
swarmvault graph update .                      # code-only refresh of tracked roots
swarmvault graph update --file ./src/auth.ts   # refresh just the named files (repeatable)

graph status recommends graph update when changes are code-only and compile when non-code sources changed or graph/report artifacts are missing. The --file fast path refreshes just the named files instead of walking every tracked root; concurrent refreshes coalesce through a lock plus queue under state/watch/. Installed Claude Code hooks run the per-file refresh automatically in the background after edits, and the same surface is available over MCP as graph_status and update_graph.

Host typecheck or lint errors on vault artifact directories

SwarmVault stores source copies under raw/ and generated pages under wiki/, which can break a host project's tsc or lint run when those directories are not excluded. Current releases handle this automatically during swarmvault install --agent <agent>: the artifact directories (raw/, wiki/, state/, agent/, inbox/) are appended to .gitignore in git repos and added to a strict-JSON tsconfig.json "exclude" list, and the install warns when linter configs still cover the artifact directories.

Commented (JSONC) tsconfig files are never rewritten — the install prints a warning so you can add the exclusions manually. If ESLint or another linter still picks up the artifact directories, add them to that tool's ignore list. All hygiene edits are skipped when SWARMVAULT_OUT keeps artifacts outside the repo.

Agent searches are being denied

Search denial only happens after an explicit opt-in: installing with swarmvault install --agent claude --hook --graph-first, or setting hooks.graphFirst: "deny" in swarmvault.config.json. With the opt-in, the first broad Grep/Glob/Bash search per session is denied once with a redirect to the plain swarmvault graph query|explain|path commands (the deny message warns against --json, which produces much larger output). swarmvault graph query "<seed>" prints the top matches with page paths plus an inline excerpt of the best-matching wiki page, so one command usually answers where-is/what-calls questions without follow-up file reads. This is a one-time guided redirect: repeating the same search is then allowed, so work is never blocked. Searches scoped to vault artifact directories (wiki/, raw/, state/), single files, or search tools filtering piped output are never intercepted.

To change or disable the behavior:

SWARMVAULT_GRAPH_FIRST=context   # session guidance only, no search interception
SWARMVAULT_GRAPH_FIRST=off       # disable graph-first behavior entirely

Or set hooks.graphFirst to deny, context, or off in swarmvault.config.json. The default without an opt-in is context (advisory).

Agent hook is not firing

Reinstall the hook in the project root and check the installed entries:

swarmvault install --agent claude --hook
swarmvault install status --agent claude --hook

Verify that .claude/settings.json contains the SwarmVault hook entries and .claude/hooks/swarmvault-graph-first.js exists. Reinstalling migrates older hook settings entries to the current matcher layout while preserving user-owned entries. User-scope installs (--scope user) intentionally no-op in repos without a compiled wiki/graph/report.md; run swarmvault compile first.

Task is missing from the graph

Tasks write immediately to state/memory/tasks/ and wiki/memory/tasks/, but graph nodes appear after compile:

swarmvault task list
swarmvault task resume <task-id>
swarmvault compile

After compile, task and decision nodes are available in state/graph.json and the graph viewer. Existing memory commands remain compatibility aliases.

MCP server is not responding

Verify the server starts correctly:

swarmvault mcp 2>&1 | head -5

The MCP server communicates over stdio. Make sure your client is configured to launch swarmvault mcp as a subprocess, not connect to a TCP port.

If an MCP client reports unacceptable kind of an object to dump [object Undefined] or a SQLite message such as no such column: robust from a hyphenated target, upgrade SwarmVault and restart the client subprocess:

npm install -g @swarmvaultai/cli@latest
swarmvault --version

SwarmVault 3.14.1 and newer normalize optional MCP response fields and retry hyphenated retrieval targets with conservative FTS tokenization.

Ingest fails on a URL

Remote URL ingest requires network access and may fail on paywalled or JavaScript-rendered pages. For better results:

• Use swarmvault add <url> for research sources (arXiv, DOI, articles, X/Twitter) which use specialized capture
• Save the page as a browser clip bundle in inbox/ and use swarmvault inbox import
• Download the page manually and ingest the local file