Troubleshooting

Common issues that you might run into while using the Couchbase MCP Server and their solutions.

uv / uvx Issues

If you see errors related to uv or uvx, check the following:

• uvx not found: Ensure uv is on your system PATH. Install uv following the official instructions. If installed via a package manager, verify it's on your PATH.

  • Run which uv (macOS/Linux) or where uv (Windows) to find the path. You may need to provide the absolute path to uv/uvx in the command field of your MCP client configuration.

• After updating source code, run uv sync to update dependencies. This is only required when running from source after pulling new changes.

Connection Issues

If you see errors related to connecting to the Couchbase cluster, check the following:

• Check credentials - Ensure your connection string, username, password, or certificate paths are correct.

• Cluster accessibility - Ensure the cluster is accessible from the machine running the MCP server. If using Couchbase Capella, ensure the machine's IP is allowed in the cluster settings — required only when connecting over the public internet, not on a VPC or a private network to Capella.

• Bucket permissions - Check that the database user has proper permissions to access at least one bucket.

• Connection string format - Use couchbases:// for Capella and TLS-enabled clusters, couchbase:// for unencrypted local connections.

  • Use couchbase:// for unencrypted connections

• Certificates for TLS - If you are connecting with TLS enabled on non-Capella clusters, ensure that the certificate is configured correctly via CB_CA_CERT_PATH.

Transport Mode Issues

If the MCP client is unable to communicate with the server, check the following based on your configured transport mode:

• stdio - Ensure the MCP client is configured to launch the server as a subprocess. Check the client's server configuration for the correct command and arguments to start the server.

• HTTP - Check that the configured port is not in use. Verify that the URL ends with /mcp. Also check if the client configuration is set correctly.

• Port conflicts - If the default port 8000 is in use, set a different port with CB_MCP_PORT or --port.

• Host binding - By default, the server binds to 127.0.0.1 (localhost only). To allow external connections, set CB_MCP_HOST=0.0.0.0 or --host.

Read-Only Mode Issues

If you are trying to perform write operations but they are not working as expected, check the following:

• Check whether CB_MCP_READ_ONLY_MODE=true (the default).

• When CB_MCP_READ_ONLY_MODE=true, KV write tools are not loaded and SQL++ write queries are blocked. Set CB_MCP_READ_ONLY_MODE=false to allow write operations.

• See Read-Only Mode for the full behavior reference.

Tool Disabling Issues

If a tool you expect to be disabled is still executing, check the following:

• Verify tool names are spelled exactly as listed in the Tools reference.

• If using a file path for CB_MCP_DISABLED_TOOLS, ensure the file exists and is readable by the server process. If using Docker, ensure the file is included in the container and the path is correct.

• Remember that disabling tools alone does not prevent operations - RBAC is the authoritative security control. See Security.

Elicitation/Tools Requiring Confirmation

If the tool you expect to require confirmation is executing without it, check the following:

• Ensure that the MCP client supports Elicitation. If the client does not support it, the tools will be executed without requiring confirmation.

• Verify tool names are spelled exactly as listed in the Tools reference.

• If using a file path for CB_MCP_CONFIRMATION_REQUIRED_TOOLS, ensure the file exists and is readable by the server process. If using Docker, ensure the file is included in the container and the path is correct.

Environment Variable Issues

If you are setting environment variables but they do not seem to be taking effect, check the following:

• Variables not taking effect - Ensure variables are set in the env block of your MCP client configuration, not as system environment variables (unless your client supports that).

• CLI vs environment variable conflicts - Command line arguments take priority over environment variables. If a setting is not behaving as expected, check if it is being overridden by a CLI argument.

• See Environment Variables for the full reference.

OAuth Issues

OAuth applies only to the Streamable HTTP transport — it is ignored on stdio. For the full configuration reference, see OAuth.

Quick first-pass diagnosis

Before digging in, confirm these five things — a surprising number of OAuth issues are resolved here:

#	Check	Expected
1	What transport is the server on?	Streamable HTTP (--transport=http); OAuth is ignored on stdio
2	What does the startup log say about OAuth?	One of OAuth enabled …, OAuth disabled …, or OAuth settings provided but transport=…
3	Does the PRM endpoint respond?	curl -s http://<host>:<port>/.well-known/oauth-protected-resource/mcp returns JSON (only when --oauth-mcp-base-url is set)
4	Does an unauthenticated tool call return 401?	A POST to /mcp with no token → 401 Unauthorized
5	Decode a sample token and confirm iss, aud, exp, scope/scp	Values match what the server expects

Server startup

Symptom	Meaning	Fix
Incomplete OAuth configuration. To enable OAuth, set all of: …	You set some but not all of the required JWT settings.	OAuth is all-or-nothing: set all of CB_MCP_OAUTH_JWT_ISSUER, CB_MCP_OAUTH_JWT_AUDIENCE, CB_MCP_OAUTH_JWT_JWKS_URI, or none. The server refuses to start on partial config so OAuth never silently fails to enable.
…issuer must be a valid http(s) URL …	You enabled PRM (--oauth-mcp-base-url) but the issuer isn't a URL.	With PRM, the issuer is published as the authorization-server URL and must be a valid http(s)://…. In token-only mode (no --oauth-mcp-base-url), any plain string works.
Log: OAuth disabled (no … settings provided)	The server is running with no OAuth — all requests are accepted unauthenticated.	You passed none of the OAuth settings (a dropped shell line-continuation \ is a frequent culprit), or set them in a different shell than the one you launched from. Verify with env | grep CB_MCP_OAUTH in the same shell, or hardcode the values on one launch line.
Log: OAuth settings provided but transport=stdio; …only honored for streamable-http	OAuth flags were detected but the server started on stdio.	Add --transport=http. OAuth applies only to Streamable HTTP.
Log: …MCP_BASE_URL set without any JWT settings; ignoring	You asked for PRM but configured no token verifier.	Set the JWT settings. PRM is meaningless without a verifier — it advertises an authorization server but validates nothing.
/.well-known/oauth-protected-resource/mcp returns 404	PRM isn't mounted.	PRM is published only when --oauth-mcp-base-url is set. Also confirm you include the /mcp suffix (per RFC 9728 the mount path is appended).

401 Unauthorized — token validation

Returned by the auth middleware before any tool runs; the log shows Auth error returned: invalid_token (status=401). Decode the token and compare it against your server config.

Symptom	Meaning	Fix
audience mismatch (got 'X', expected 'Y')	Token's aud ≠ --oauth-audience.	Decode a sample token, copy the aud value verbatim, and set --oauth-audience to match exactly (no trailing-slash differences). Note that some IdPs emit a different aud per grant type.
issuer mismatch (got 'X', expected 'Y')	Token's iss ≠ --oauth-issuer.	Decode a token, copy iss verbatim, and match it. A trailing-slash difference is the most common cause.
token expired	The exp claim is in the past.	Mint a fresh token. If you suspect clock skew, run NTP on the server host — the server applies no leeway by default.

403 Forbidden — scope enforcement

Returned after JWT validation succeeds; the message names the required and missing scopes.

Symptom	Meaning	Fix
Tool 'X' requires scope(s) ['couchbase-mcp:read']; token is missing …	The token doesn't carry the required scope.	Decode the token and check both the scope (space-separated string) and scp (array) claims. Mint a token that includes the needed scope.
SQL++ tool rejected for a write-only token	By design, couchbase-mcp:write permits KV mutations only; SQL++ is classified as a read tool.	If the agent must run SQL++, mint a token carrying both couchbase-mcp:read and couchbase-mcp:write.
SQL++ INSERT/UPDATE rejected even with both scopes	Read-only mode is on, or the token lacks couchbase-mcp:write.	Set CB_MCP_READ_ONLY_MODE=false (or --read-only-mode=false) and confirm the token has both scopes.

Couchbase-layer errors (after OAuth succeeds)

These appear after the JWT validated and the scope check passed — they come from the Couchbase SDK or RBAC, not the OAuth layer.

Symptom	Meaning	Fix
AuthenticationException(<ec=6, …>) from the SDK	CB_USERNAME / CB_PASSWORD don't authenticate against CB_CONNECTION_STRING.	Verify the cluster credentials directly — curl -u "$CB_USERNAME:$CB_PASSWORD" "<host>:8091/pools" should return 200. Check the connection scheme (couchbase:// vs couchbases://) and reachability.
InvalidArgumentException(<message=The username must be a str.>)	The server started without cluster credentials.	Set CB_CONNECTION_STRING, CB_USERNAME, and CB_PASSWORD.
Reads succeed but writes fail	The Couchbase user lacks RBAC write permission on the target keyspace.	RBAC is the ultimate authority — even a valid couchbase-mcp:write token can't exceed the server's cluster credentials. Grant read/write (or equivalent) on the target bucket/scope.

Logging Issues

The MCP server's own logging is configured at startup through environment variables or CLI flags — see Logging for the full configuration reference. Every start emits one INFO boot summary line reporting the resolved configuration: the level in effect, which sinks are live, and the exact file paths being written. For example:

2026-06-29T18:08:49+0530 - couchbase - INFO - Logging configured: level=INFO, sinks=stderr,file, log_files={'INFO': 'mcp_server.info.log', 'WARNING': 'mcp_server.warning.log', 'ERROR': 'mcp_server.error.log'}, max_bytes=1048576

When logging behaves unexpectedly, read this line first — then work through the table below.

Symptom	Likely cause	Fix
No log files anywhere	The file sink isn't enabled — the default is stderr only.	Set CB_MCP_LOG_SINKS=stderr,file (or --log-sinks file). Confirm via the boot summary line.
Files exist but one stays empty	Each level's file is filtered to exactly its level, so an idle server may legitimately have an empty warning/error file.	This is expected. The info file should grow during normal use; if it doesn't, recheck the level and sinks in the boot line.
A per-level file I expected is missing (e.g. no debug file, or no info/warning file)	That level is below the configured threshold — a file is created only for levels at or above CB_MCP_LOG_LEVEL.	Lower the level to include it: --log-level=debug produces all four files; at warning, only the warning + error files exist.
Server logged "File logging is disabled…" warning	The file sink was not requested, so support files aren't being persisted.	Expected when running stderr-only. Add file to --log-sinks if you need persisted logs.
I set a log level and nothing changed	An invalid level value silently fell back to info.	Check the boot output for Ignored invalid log level …. Valid values are off/debug/info/warning/error.
A sink I configured is being ignored	An unrecognized --log-sinks token was dropped.	Look for Ignored invalid log sink value(s) … at startup. Valid tokens are stderr and file only.
Files grow without bound / fill the disk	Rotation was disabled with --log-max-bytes=0.	Set a non-zero size. With the default 1 MB and one backup, each level caps at ~2 MB on disk.
ERROR lines I want to suppress keep appearing	ERROR cannot be raised away — only off silences it.	Set CB_MCP_LOG_LEVEL=off to silence everything (understanding you lose error visibility too).
An ERROR line has no stack trace	Stack traces are emitted at DEBUG, by design — ERROR stays a clean one-liner.	Re-run at --log-level=debug to capture the traceback for the same failure.
No logs at all from the server	Either --log-level=off, or you're looking in the wrong place (the client captures stderr).	Confirm the boot line appears; for stdio clients, see Checking Logs below for client log locations.

Checking Logs

To configure the MCP server's own logs — log level, console/file output, and file logging for support — see Logging.

The MCP client also keeps its own logs. Check the MCP client logs for errors or warnings:

Client	Log Location
Claude Desktop	~/Library/Logs/Claude (macOS), %APPDATA%\Claude\Logs (Windows)
Cursor	Bottom panel > Output > "Cursor MCP"
Windsurf	Check Windsurf output panel
VS Code	Command Palette > "MCP: List Servers" > Show Output
JetBrains	Help > Show Log in Finder/Explorer > mcp > couchbase
Factory	~/.factory/logs/ (macOS)