Skip to content

Troubleshooting

Web Server Does Not Start

Symptom: The web server fails to start or you can't reach http://localhost:5244.

Fix:

  1. Make sure you have the .NET 10 SDK installed.
  2. Try starting manually: dotnet run --project src/NexusLabs.Narnia.Web and check the output for errors.
  3. Check if something else is already using port 5244 (netstat -an | findstr 5244 on Windows).
  4. If using the narnia-web-server skill, the LLM will show you the build output and can diagnose issues automatically.

Web Server Starts But Can't Connect

Symptom: The server process is running but http://localhost:5244 gives "connection refused."

Fix:

  1. Wait a few seconds — cold builds can take 30-60+ seconds.
  2. Check the server process output for binding errors.
  3. If port 5244 is in use, change applicationUrl in src/NexusLabs.Narnia.Web/Properties/launchSettings.json.

Sessions Not Found by Repository or CWD

Symptom: list_sessions_by_repository or list_sessions_by_cwd returns an empty array.

Why it happens: Repository and working-directory tools filter metadata, not conversation keywords. Repository matching uses the effective value after Narnia overrides. Working-directory matching does not convert forward slashes to backslashes.

Fix:

  • Use list_recent_sessions first to see the effective repository and recorded cwd values.
  • Copy the relevant field into the matching tool; do not pass a local path to list_sessions_by_repository.
  • On Windows, paths are stored with backslashes — use C:\dev\myproject, not C:/dev/myproject.
  • Repository matching is case-insensitive. Working-directory matching is case-insensitive on Windows and case-sensitive on case-sensitive operating systems.

.NET 10 SDK Not Found

Symptom: Running dotnet run --project src/NexusLabs.Narnia.Web (or dotnet build narnia.slnx) fails with "The required .NET version was not found."

Fix: Install the .NET 10 SDK. The Narnia projects target net10.0 and require the .NET 10 runtime.

MCP Client Shows No Tools / Can't Connect

Symptom: Your MCP client (VS Code, Cursor, Visual Studio, Claude Desktop) shows Narnia as errored, disconnected, or with zero tools available.

Why it happens: Narnia's MCP server is not a process your client launches itself — it's the /mcp endpoint of the already-running Narnia web server. If that server isn't up, there is nothing listening at http://127.0.0.1:5244/mcp to connect to.

Fix:

  1. Check http://127.0.0.1:5244/health in a browser (or curl) — a connection failure means the server isn't running.
  2. Start it: see Getting Started, or ask the narnia-web-server skill to start it.
  3. GitHub Copilot CLI keeps the server running automatically via a sessionStart hook once Narnia is installed as a plugin. Other clients (VS Code, Cursor, Visual Studio, Claude Desktop) don't manage this for you — start the server yourself first.
  4. Reconnect or reload tools in your MCP client once /health returns 200.

Database File Not Found

Symptom: All MCP tools return errors mentioning "unable to open database file" or similar SQLite errors.

Why it happens: The default database path (~/.copilot/session-store.db) does not exist, or Narnia is looking in the wrong location.

Fix:

  1. Confirm the file exists: on Windows, check C:\Users\{your-username}\.copilot\session-store.db.
  2. If it's in a different location, set NARNIA__DatabasePath to the correct absolute path for the server process (see Configuration) — not in a per-client MCP config, since the server is a single always-on process shared by every client.
  3. If you've never used Copilot CLI, the database won't exist yet — you need to start at least one Copilot CLI session first.

Search Returns No Results

Symptom: search_sessions returns an empty array for queries that should match.

Why it happens: The FTS5 index may not contain the expected content, or the query syntax is incorrect.

Fix:

  • Try a simpler query first: a single common word that should appear in your sessions.
  • Use prefix matching for partial words: auth* instead of authorization.
  • Use list_sessions_by_repository or list_sessions_by_cwd for metadata; search_sessions only searches indexed content.
  • Verify sessions exist with list_recent_sessions — if that also returns nothing, the database path is likely wrong.