SQLite MCP: no such table on a populated DB (server auto-created an empty file)

Not specified by the original author.

TL;DR: no such table on a database you know is populated usually means the server opened the wrong file. The SQLite MCP server silently creates an empty database when the path does not exist, so a typo in --db-path gives you a working server with zero tables. Fix the path, delete the stray empty file, restart.

Error: no such table: users

Fix it

1. Check whether the path in your config actually holds your data URIs

ls -la /path/from/your/config/app.db
sqlite3 /path/from/your/config/app.db ".tables"

Expected if this is the bug: the file exists but .tables prints nothing. It is an empty database the server created for you.

2. Find the real database file:

find [HOME]/... -name "app.db" -size +0c 2>/dev/null

Look for the non-empty one.

3. Point --db-path at the real file (absolute path), delete the stray empty file, and restart the MCP client.

   Expected: read_query and table listing tools now see your tables.

When to use this

• The server starts fine and connects, but every table you query is missing.
• .tables on the configured path shows nothing, yet you know the data exists somewhere.

When NOT to use this

• The error is unable to open database file. That is a path/permission problem, not a wrong-file problem.
• The database genuinely has no tables yet. Then the fix is creating them, not fixing the path.

Compatibility

• @modelcontextprotocol/server-sqlite, and any MCP server that opens SQLite with create-if-missing semantics.

Why it happens

SQLite's default open mode creates the file if missing. That is convenient for new projects and treacherous for typos: instead of failing loudly, the server happily serves an empty database. The mismatch only surfaces when you query a table that exists in the real file but not in the accidental one.

Edge cases

• The stray file also gets -wal and -shm companions if WAL mode was used. Delete those too.
• If two configs point at two different files, each spawns its own empty DB. Consolidate to one path.
• Back up the real file before deleting anything, in case the stray file is actually the one with recent writes.

The @modelcontextprotocol/server-sqlite creates the SQLite file at --db-path if it does not exist (standard SQLite open behavior), which means a typo in the path produces a working server against an empty database instead of an error. The symptom reported by users is queries failing with no such table on a database they believe is populated. The fix is verifying the path points at the real file and removing the accidentally created empty file. This behavior is inherent to how the server opens its database.

Not specified by the original author.

TL;DR: The SQLite MCP server cannot find your database because the --db-path you gave it is relative, and the server resolves it against its own working directory, not yours. Pass an absolute path to the database file in your client config and the error goes away.

Error: unable to open database file

Fix it

1. Replace the relative path with an absolute one in your MCP client config:

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "[HOME]/..."]
    }
  }
}

On Windows use the full drive path, e.g. C:[HOME]/....

2. Fully quit and restart the MCP client so the server respawns with the new argument.

   Expected: the server starts and tools like read_query list your tables. No open error in the logs.

3. If it still fails, check the parent directory exists. SQLite cannot create missing parent directories, only the file itself:

ls -la [HOME]/...

When to use this

• The database file exists and opens fine in the sqlite3 CLI, but the MCP server says it cannot open it.
• You used a relative path, ~, or an env-var-style path in --db-path.

When NOT to use this

• The error is no such table. The file opened fine; you are pointing at the wrong (probably auto-created empty) database.
• The error is database is locked. That is a concurrency problem, not a path problem.

Compatibility

• @modelcontextprotocol/server-sqlite (takes --db-path).
• Claude Desktop, Claude Code, Cursor, Windsurf.

Why it happens

GUI MCP clients launch the server as a child process with an unpredictable working directory (often the app bundle or system root). A relative --db-path like data/app.db resolves against that directory, not your project. SQLite then fails to open it because the parent directory does not exist there. Absolute paths remove the ambiguity entirely.

Edge cases

• ~ is not expanded by the server. Write out [HOME]/... (or C:[HOME]/...) in full.
• Paths with spaces work if quoted correctly in JSON. The JSON string quoting handles it; do not add shell quotes inside the arg.
• If the parent directory is missing, create it first. The server will create the .db file itself if it does not exist.

The statcan-mcp-server project (Aryan-Jhaveri/mcp-statcan) lists this as an active known issue in its README: Unable to open database file on Claude Desktop, with the workaround to pass --db-path with a full absolute path. This is the same failure mode as the official @modelcontextprotocol/server-sqlite, which takes --db-path as its argument and resolves it relative to the server process working directory, which under a GUI MCP client is not the user's shell directory. Source: https://github.com/aryan-jhaveri/mcp-statcan

Not specified by the original author.

TL;DR: ~ in --db-path does not mean your home directory to the SQLite MCP server. Tilde expansion is a shell feature and the server is launched without a shell, so it looks for a literal directory named ~ and fails. Write out the full path.

Error: unable to open database file

(With --db-path set to something like ~/data/app.db.)

Fix it

1. In your MCP client config, replace the tilde with the real home directory:

{
  "args": ["mcp-server-sqlite", "--db-path", "[HOME]/..."]
}

Find your home directory with echo $HOME in a terminal.

2. Restart the MCP client.

   Expected: the server opens the database and tools work.

When to use this

• --db-path contains ~ and the server cannot open the file.
• The same path works when pasted into a terminal (because your shell expands the tilde there).

When NOT to use this

• The path has no tilde and still fails. Then it is a permissions or missing-directory problem.
• The error is no such table. The file opened; it is just the wrong or an empty one.

Compatibility

• @modelcontextprotocol/server-sqlite.
• All MCP clients, since none of them run a shell to expand the argument.

Why it happens

When you type ~/data/app.db in a terminal, your shell rewrites it to [HOME]/... before the program ever sees it. MCP clients spawn servers directly via process APIs, with no shell in between, so the server receives the literal two-character string ~/... and treats it as a relative path. There is no ~ directory, so the open fails.

Edge cases

• Environment variables like $HOME in args are not expanded either, for the same reason. Some clients support ${HOME} in the env block, but not in args.
• On Windows, %USERPROFILE% is not expanded in args either. Use the full C:[HOME]/... path.
• If you generate configs with a script, expand the path in the script before writing the JSON.

The @modelcontextprotocol/server-sqlite takes --db-path as a literal argument and does not expand ~ (tilde expansion is a shell feature, and MCP clients spawn the server directly without a shell). Users configuring --db-path as ~/data/app.db get unable to open database file because the server looks for a directory literally named ~. The fix is using the absolute path with the home directory written out. This is the same class of issue as the documented absolute-path requirement for Claude Desktop configurations.