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

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