nextcloud-mcp-server/docs/troubleshooting.md

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, smithery

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
MCP_DEPLOYMENT_MODE=smithery                   # Smithery deployment

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:

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

Solution:

Option 1: Enable dynamic client registration

1. 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

2. Enable dynamic client registration:

   • Go to Settings → OIDC (Administration)
   • Enable "Allow dynamic client registration"

3. 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
   

4. 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

Register a client and add credentials to .env:

# 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:

1. Verify the Nextcloud URL is correct:

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

2. Test the discovery endpoint manually:

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

3. Check network connectivity:

   ping your.nextcloud.instance.com
   

4. Verify both OIDC apps are installed and enabled in Nextcloud:

   • oidc - OIDC Identity Provider
   • user_oidc - OpenID Connect user backend

5. 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:

1. Verify username:

   # Username should match your Nextcloud login
   echo $NEXTCLOUD_USERNAME
   

2. 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

3. 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:

1. Check server binding:

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

2. 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
   

3. 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:

1. Check logs with debug level:

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

2. Monitor resource usage:

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

3. 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
   

4. 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:

1. Verify OAuth is configured correctly:

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

2. Check that OIDC app is accessible:

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

3. Verify MCP_SERVER_URL matches your setup:

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

For BasicAuth:

1. 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:

1. Verify required Nextcloud apps are installed:

   • Notes: Install "Notes" app
   • Calendar: Ensure CalDAV is enabled
   • Contacts: Ensure CardDAV is enabled
   • Deck: Install "Deck" app

2. Check user permissions:

   • Ensure the authenticated user has access to the resources
   • Check sharing permissions for shared resources

3. 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"
   

4. 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)

---

See Also

• OAuth Troubleshooting - Dedicated OAuth troubleshooting guide
• OAuth Setup Guide - OAuth configuration
• OAuth Architecture - How OAuth works
• Upstream Status - Required patches and upstream PRs
• Configuration - Environment variables
• Running the Server - Server options