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

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

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.

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