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.

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