Troubleshooting

This guide covers common issues and solutions for the Nextcloud MCP server.

OAuth-specific issues? See the dedicated OAuth Troubleshooting Guide for OAuth authentication problems, OIDC discovery issues, token validation failures, and more.

Upgrading from v0.57.x? See the Configuration Migration Guide for help with new variable names.

Configuration Issues (v0.58.0+)

Issue: Deprecation warning for VECTOR_SYNC_ENABLED

Symptom:

WARNING: VECTOR_SYNC_ENABLED is deprecated. Please use ENABLE_SEMANTIC_SEARCH instead.

Cause: You're using the old variable name from v0.57.x.

Solution:

# In your .env file, replace:
VECTOR_SYNC_ENABLED=true

# With:
ENABLE_SEMANTIC_SEARCH=true

See Configuration Migration Guide for complete migration instructions.

Issue: Deprecation warning for ENABLE_OFFLINE_ACCESS

Symptom:

WARNING: ENABLE_OFFLINE_ACCESS is deprecated. Please use ENABLE_BACKGROUND_OPERATIONS instead.

Cause: You're using the old variable name from v0.57.x.

Solution:

If you have semantic search enabled:

# In multi-user modes, you can remove ENABLE_OFFLINE_ACCESS entirely!
# ENABLE_SEMANTIC_SEARCH automatically enables background operations

# Before (v0.57.x):
ENABLE_OFFLINE_ACCESS=true
VECTOR_SYNC_ENABLED=true

# After (v0.58.0+):
ENABLE_SEMANTIC_SEARCH=true  # This is all you need!

If you only want background operations (no semantic search):

# Replace:
ENABLE_OFFLINE_ACCESS=true

# With:
ENABLE_BACKGROUND_OPERATIONS=true

Issue: "Invalid MCP_DEPLOYMENT_MODE"

Symptom:

ValueError: Invalid MCP_DEPLOYMENT_MODE: 'oauth'. Valid values: single_user_basic, multi_user_basic, oauth_single_audience, oauth_token_exchange

Cause: Invalid value for MCP_DEPLOYMENT_MODE.

Solution: Use one of the valid mode values:

# Correct values:
MCP_DEPLOYMENT_MODE=single_user_basic          # Single-user with username/password
MCP_DEPLOYMENT_MODE=multi_user_basic           # Multi-user BasicAuth
MCP_DEPLOYMENT_MODE=oauth_single_audience      # OAuth (recommended)
MCP_DEPLOYMENT_MODE=oauth_token_exchange       # OAuth with token exchange

Or remove MCP_DEPLOYMENT_MODE to use automatic detection.

Issue: Missing TOKEN_ENCRYPTION_KEY when semantic search enabled

Symptom:

Error: [oauth_single_audience] TOKEN_ENCRYPTION_KEY is required when ENABLE_SEMANTIC_SEARCH is enabled

Cause: In multi-user modes, semantic search automatically enables background operations, which require encrypted token storage.

Solution: Generate an encryption key and add required token storage configuration:

# Generate encryption key
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

# Add to .env:
TOKEN_ENCRYPTION_KEY=<generated-key>
TOKEN_STORAGE_DB=/app/data/tokens.db
NEXTCLOUD_OIDC_CLIENT_ID=your-client-id       # Required for app password retrieval
NEXTCLOUD_OIDC_CLIENT_SECRET=your-client-secret

Why this happens:

v0.58.0+ automatically enables background operations when ENABLE_SEMANTIC_SEARCH=true in multi-user modes
Background operations need encrypted refresh token storage
This simplifies configuration but requires the encryption infrastructure

See Configuration Guide - Semantic Search for details.

Issue: Both old and new variable names set

Symptom:

WARNING: Both ENABLE_SEMANTIC_SEARCH and VECTOR_SYNC_ENABLED are set. Using ENABLE_SEMANTIC_SEARCH.

Cause: You have both the old and new variable names in your configuration.

Solution: Remove the old variable name:

# Remove this line:
VECTOR_SYNC_ENABLED=true

# Keep this line:
ENABLE_SEMANTIC_SEARCH=true

The server will use the new name and ignore the old one, but it's cleaner to remove the old variable entirely.

OAuth Issues (Quick Reference)

Issue: "OAuth mode requires NEXTCLOUD_HOST environment variable"

Cause: The NEXTCLOUD_HOST environment variable is not set or empty.

Solution:

# Ensure NEXTCLOUD_HOST is set in your .env file
echo "NEXTCLOUD_HOST=https://your.nextcloud.instance.com" >> .env

# Load environment variables
export $(grep -v '^#' .env | xargs)

# Verify it's set
echo $NEXTCLOUD_HOST

Issue: "OAuth mode requires either client credentials OR dynamic client registration"

Cause: The required Nextcloud OIDC apps are either:

Not installed (both oidc and user_oidc apps are required)
Don't have dynamic client registration enabled
Aren't providing a registration endpoint

Solution:

Option 1: Enable dynamic client registration

Verify both OIDC apps are installed:
- Navigate to Nextcloud Apps → Security
- Install "OIDC" (OIDC Identity Provider app) if not present
- Install "OpenID Connect user backend" (user_oidc app) if not present
Enable dynamic client registration:
- Go to Settings → OIDC (Administration)
- Enable "Allow dynamic client registration"

Configure Bearer token validation:

# Required for user_oidc app to validate tokens
php occ config:system:set user_oidc oidc_provider_bearer_validation --value=true --type=boolean

Verify the registration endpoint exists:

curl https://your.nextcloud.instance.com/.well-known/openid-configuration | jq '.registration_endpoint'
# Should output: "https://your.nextcloud.instance.com/apps/oidc/register"

Option 2: Provide pre-configured credentials

# On your Nextcloud server
php occ oidc:create \
  --name="Nextcloud MCP Server" \
  --type=confidential \
  --redirect-uri="http://localhost:8000/oauth/callback"

# Add to .env
echo "NEXTCLOUD_OIDC_CLIENT_ID=<from-output>" >> .env
echo "NEXTCLOUD_OIDC_CLIENT_SECRET=<from-output>" >> .env

See OAuth Setup Guide for detailed instructions.

Issue: "Stored client has expired"

Cause: Dynamically registered OAuth clients expire (default: 1 hour).

Solution:

Option 1: Restart the server (automatic re-registration)

# Server checks credentials at startup and re-registers if expired
uv run nextcloud-mcp-server --oauth

Option 2: Use pre-configured credentials (recommended for production)

# Register permanent client via Nextcloud CLI
php occ oidc:create \
  --name="Nextcloud MCP Server" \
  --type=confidential \
  --redirect-uri="http://localhost:8000/oauth/callback"

# Add to .env
NEXTCLOUD_OIDC_CLIENT_ID=<from-output>
NEXTCLOUD_OIDC_CLIENT_SECRET=<from-output>

Option 3: Increase expiration time

# Via Nextcloud occ command (default: 3600 seconds)
php occ config:app:set oidc expire_time --value "86400"  # 24 hours

Issue: "HTTP 401 Unauthorized" when calling Nextcloud APIs

Cause: OAuth Bearer tokens may not work with certain Nextcloud endpoints due to session handling in the CORS middleware.

Background: The user_oidc app's CORS middleware interferes with Bearer token authentication for non-OCS endpoints (like Notes API). This affects app-specific APIs but not OCS APIs.

Solution:

A patch for the user_oidc app is required to fix Bearer token support. See oauth2-bearer-token-session-issue.md for:

Detailed explanation of the issue
Patch to apply to the user_oidc app
Link to upstream pull request

Affected endpoints:

Notes API (/apps/notes/api/)
Other app-specific endpoints

Unaffected endpoints:

OCS APIs (/ocs/v2.php/)
Capabilities endpoint

Issue: "Permission denied" or "Database is locked" when accessing OAuth client storage

Cause: The server cannot access the SQLite database for OAuth client credentials storage.

Solution:

# Check database directory permissions
ls -la data/

# Ensure directory is writable
chmod 755 data/

# Check if database file exists and has correct permissions
ls -la data/tokens.db
chmod 644 data/tokens.db

# For Docker deployments, ensure volume is mounted correctly:
# docker-compose.yml should have:
#   volumes:
#     - ./data:/app/data

Issue: "OIDC discovery failed" or "Cannot reach OIDC discovery endpoint"

Cause: The server cannot reach the Nextcloud OIDC discovery endpoint.

Solution:

Verify the Nextcloud URL is correct:

echo $NEXTCLOUD_HOST
# Should be the full URL: https://your.nextcloud.instance.com

Test the discovery endpoint manually:

curl https://your.nextcloud.instance.com/.well-known/openid-configuration
# Should return JSON with OIDC configuration

Check network connectivity:
```
ping your.nextcloud.instance.com
```
Verify both OIDC apps are installed and enabled in Nextcloud:
- oidc - OIDC Identity Provider
- user_oidc - OpenID Connect user backend
Check firewall rules if using Docker

Switching Between OAuth and BasicAuth

To switch from BasicAuth to OAuth:

# 1. Remove or comment out USERNAME/PASSWORD in .env
sed -i 's/^NEXTCLOUD_USERNAME/#NEXTCLOUD_USERNAME/' .env
sed -i 's/^NEXTCLOUD_PASSWORD/#NEXTCLOUD_PASSWORD/' .env

# 2. Ensure NEXTCLOUD_HOST is set
grep NEXTCLOUD_HOST .env

# 3. Restart server with OAuth
export $(grep -v '^#' .env | xargs)
uv run nextcloud-mcp-server --oauth

To switch from OAuth to BasicAuth:

# 1. Add USERNAME/PASSWORD to .env
echo "NEXTCLOUD_USERNAME=your-username" >> .env
echo "NEXTCLOUD_PASSWORD=your-password" >> .env

# 2. Restart server (BasicAuth auto-detected, or use --no-oauth)
export $(grep -v '^#' .env | xargs)
uv run nextcloud-mcp-server --no-oauth

For More OAuth Help

See the dedicated OAuth Troubleshooting Guide for:

Bearer token authentication failures
PKCE validation errors
Token validation issues
Client registration problems
Advanced OAuth debugging
And much more...

Configuration Issues

Issue: Environment variables not loaded

Cause: Environment variables from .env file are not loaded into the shell.

Solution:

On Linux/macOS:

# Load all variables from .env
export $(grep -v '^#' .env | xargs)

# Verify variables are set
env | grep NEXTCLOUD

On Windows (PowerShell):

# Load variables from .env
Get-Content .env | ForEach-Object {
    if ($_ -match '^\s*([^#][^=]*)\s*=\s*(.*)$') {
        [Environment]::SetEnvironmentVariable($matches[1].Trim(), $matches[2].Trim(), "Process")
    }
}

# Verify variables are set
Get-ChildItem Env:NEXTCLOUD*

With Docker:

# Docker automatically loads .env when using --env-file
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest

Issue: ".env file not found"

Cause: The .env file doesn't exist or is in the wrong location.

Solution:

# Create .env from sample
cp env.sample .env

# Edit with your Nextcloud details
nano .env  # or vim, code, etc.

# Ensure you're in the correct directory when running commands
pwd  # Should be in the project directory containing .env

Issue: "Invalid Nextcloud credentials"

Cause: BasicAuth credentials are incorrect or the app password has been revoked.

Solution:

Verify username:

# Username should match your Nextcloud login
echo $NEXTCLOUD_USERNAME

Generate a new app password:
- Log in to Nextcloud
- Go to Settings → Security
- Under "Devices & sessions", create a new app password
- Update .env with the new password

Test credentials manually:

curl -u "$NEXTCLOUD_USERNAME:$NEXTCLOUD_PASSWORD" \
  "$NEXTCLOUD_HOST/ocs/v2.php/cloud/capabilities" \
  -H "OCS-APIRequest: true"
# Should return XML with capabilities

Server Issues

Issue: "Address already in use" / Port conflict

Cause: Another process is using port 8000.

Solution:

Option 1: Use a different port

uv run nextcloud-mcp-server --port 8080

Option 2: Find and kill the process using the port

# On Linux/macOS
lsof -ti:8000 | xargs kill -9

# On Windows
netstat -ano | findstr :8000
taskkill /PID <pid> /F

Option 3: Stop other MCP server instances

# Check for running instances
ps aux | grep nextcloud-mcp-server

# Kill specific process
kill <pid>

Issue: Server starts but can't connect

Cause: Server is bound to localhost only, or firewall is blocking connections.

Solution:

Check server binding:

# Bind to all interfaces to allow network access
uv run nextcloud-mcp-server --host 0.0.0.0 --port 8000

Test connectivity:

# Test from same machine
curl http://localhost:8000/health

# Test from network (if using --host 0.0.0.0)
curl http://<server-ip>:8000/health

Check firewall:

# Linux (ufw)
sudo ufw allow 8000/tcp

# Linux (firewalld)
sudo firewall-cmd --add-port=8000/tcp --permanent
sudo firewall-cmd --reload

Issue: Server crashes or restarts frequently

Cause: Various issues including memory limits, uncaught exceptions, or OAuth token expiration.

Solution:

Check logs with debug level:

uv run nextcloud-mcp-server --log-level debug

Monitor resource usage:

# Check memory and CPU
top -p $(pgrep -f nextcloud-mcp-server)

Use process manager for automatic restart:

# With systemd (see Running guide for full config)
sudo systemctl restart nextcloud-mcp

# With Docker Compose (includes restart: unless-stopped)
docker-compose up -d

Check for OAuth credential expiration (if using dynamic registration):
- See "Stored client has expired" above

Connection Issues

Issue: MCP client can't authenticate

Cause: OAuth flow failing or credentials invalid.

Solution:

For OAuth:

Verify OAuth is configured correctly:

uv run nextcloud-mcp-server --oauth --log-level debug
# Look for "OAuth initialization complete"

Check that OIDC app is accessible:

curl https://your.nextcloud.instance.com/.well-known/openid-configuration

Verify MCP_SERVER_URL matches your setup:

echo $NEXTCLOUD_MCP_SERVER_URL
# Should match the URL clients use to connect

For BasicAuth:

Verify credentials work:

curl -u "$NEXTCLOUD_USERNAME:$NEXTCLOUD_PASSWORD" \
  "$NEXTCLOUD_HOST/ocs/v2.php/cloud/capabilities" \
  -H "OCS-APIRequest: true"

Issue: Tools return errors or don't work

Cause: Missing Nextcloud apps, incorrect permissions, or API issues.

Solution:

Verify required Nextcloud apps are installed:
- Notes: Install "Notes" app
- Calendar: Ensure CalDAV is enabled
- Contacts: Ensure CardDAV is enabled
- Deck: Install "Deck" app
Check user permissions:
- Ensure the authenticated user has access to the resources
- Check sharing permissions for shared resources

Test API directly:

# Test Notes API
curl -u "$NEXTCLOUD_USERNAME:$NEXTCLOUD_PASSWORD" \
  "$NEXTCLOUD_HOST/apps/notes/api/v1/notes"

# Test with OAuth Bearer token
curl -H "Authorization: Bearer $TOKEN" \
  "$NEXTCLOUD_HOST/apps/notes/api/v1/notes"

Check server logs for specific errors:

uv run nextcloud-mcp-server --log-level debug

Getting Help

If you continue to experience issues:

1. Enable Debug Logging

uv run nextcloud-mcp-server --log-level debug

Review the logs for specific error messages.

2. Verify OIDC Configuration (OAuth mode)

# Check OIDC discovery
curl https://your.nextcloud.instance.com/.well-known/openid-configuration

# Check registration endpoint exists
curl https://your.nextcloud.instance.com/.well-known/openid-configuration | jq '.registration_endpoint'

3. Test Nextcloud API Access

# Test OCS API (should work with OAuth)
curl -H "Authorization: Bearer $TOKEN" \
  "$NEXTCLOUD_HOST/ocs/v2.php/cloud/capabilities?format=json" \
  -H "OCS-APIRequest: true"

# Test app API (may need patch - see oauth2-bearer-token-session-issue.md)
curl -H "Authorization: Bearer $TOKEN" \
  "$NEXTCLOUD_HOST/apps/notes/api/v1/notes"

4. Check Versions

# MCP Server version
uv run nextcloud-mcp-server --version

# Python version
python3 --version

# Nextcloud version (check in admin panel)

5. Open an Issue

If problems persist, open an issue on the GitHub repository with:

Server logs (with --log-level debug)
Nextcloud version
OIDC app version (if using OAuth)
Error messages
Steps to reproduce
Environment details (OS, Python version, Docker vs local)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Troubleshooting

Configuration Issues (v0.58.0+)

Issue: Deprecation warning for VECTOR_SYNC_ENABLED

Issue: Deprecation warning for ENABLE_OFFLINE_ACCESS

Issue: "Invalid MCP_DEPLOYMENT_MODE"

Issue: Missing TOKEN_ENCRYPTION_KEY when semantic search enabled

Issue: Both old and new variable names set

OAuth Issues (Quick Reference)

Issue: "OAuth mode requires NEXTCLOUD_HOST environment variable"

Issue: "OAuth mode requires either client credentials OR dynamic client registration"

Issue: "Stored client has expired"

Issue: "HTTP 401 Unauthorized" when calling Nextcloud APIs

Issue: "Permission denied" or "Database is locked" when accessing OAuth client storage

Issue: "OIDC discovery failed" or "Cannot reach OIDC discovery endpoint"

Switching Between OAuth and BasicAuth

To switch from BasicAuth to OAuth:

To switch from OAuth to BasicAuth:

For More OAuth Help

Configuration Issues

Issue: Environment variables not loaded

Issue: ".env file not found"

Issue: "Invalid Nextcloud credentials"

Server Issues

Issue: "Address already in use" / Port conflict

Issue: Server starts but can't connect

Issue: Server crashes or restarts frequently

Connection Issues

Issue: MCP client can't authenticate

Issue: Tools return errors or don't work

Getting Help

1. Enable Debug Logging

2. Verify OIDC Configuration (OAuth mode)

3. Test Nextcloud API Access

4. Check Versions

5. Open an Issue

See Also

FilesExpand file tree

troubleshooting.md

Latest commit

History

troubleshooting.md

File metadata and controls

Troubleshooting

Configuration Issues (v0.58.0+)

Issue: Deprecation warning for VECTOR_SYNC_ENABLED

Issue: Deprecation warning for ENABLE_OFFLINE_ACCESS

Issue: "Invalid MCP_DEPLOYMENT_MODE"

Issue: Missing TOKEN_ENCRYPTION_KEY when semantic search enabled

Issue: Both old and new variable names set

OAuth Issues (Quick Reference)

Issue: "OAuth mode requires NEXTCLOUD_HOST environment variable"

Issue: "OAuth mode requires either client credentials OR dynamic client registration"

Issue: "Stored client has expired"

Issue: "HTTP 401 Unauthorized" when calling Nextcloud APIs

Issue: "Permission denied" or "Database is locked" when accessing OAuth client storage

Issue: "OIDC discovery failed" or "Cannot reach OIDC discovery endpoint"

Switching Between OAuth and BasicAuth

To switch from BasicAuth to OAuth:

To switch from OAuth to BasicAuth:

For More OAuth Help

Configuration Issues

Issue: Environment variables not loaded

Issue: ".env file not found"

Issue: "Invalid Nextcloud credentials"

Server Issues

Issue: "Address already in use" / Port conflict

Issue: Server starts but can't connect

Issue: Server crashes or restarts frequently

Connection Issues

Issue: MCP client can't authenticate

Issue: Tools return errors or don't work

Getting Help

1. Enable Debug Logging

2. Verify OIDC Configuration (OAuth mode)

3. Test Nextcloud API Access

4. Check Versions

5. Open an Issue

See Also