# SmartSuite MCP Server - Troubleshooting Guide
## Quick Diagnostics
```bash
# Run comprehensive checks
npm run quality-gates
# Check environment
env | grep SMARTSUITE
# Test API connectivity
curl -H "Authorization: Token $SMARTSUITE_API_KEY" \
-H "ACCOUNT-ID: $SMARTSUITE_WORKSPACE_ID" \
https://app.smartsuite.com/api/v1/applications/
# Validate configuration
MCP_VALIDATE_AND_EXIT=true npm start
```
---
## Common Issues
### 1. Server Won't Start
#### Symptom
```
Error: SMARTSUITE_API_KEY environment variable is required
```
#### Cause
Missing or incorrectly set environment variables
#### Solution
```bash
# Create .env file from template
cp .env.example .env
# Edit with your credentials
nano .env
# Verify variables are set
echo $SMARTSUITE_API_KEY
echo $SMARTSUITE_WORKSPACE_ID
# Reload environment
source .env # or restart terminal
```
---
### 2. Authentication Failures
#### Symptom
```
Error: Authentication failed (401): Invalid API key
```
#### Causes & Solutions
**Invalid API Key**
```bash
# Verify key format (should be 40-character hex string)
echo $SMARTSUITE_API_KEY | wc -c # Should output 41 (40 + newline)
# Get new key from SmartSuite:
# Settings > API > Generate New Token
```
**Wrong Workspace ID**
```bash
# Test with curl
curl -v -H "Authorization: Token $SMARTSUITE_API_KEY" \
-H "ACCOUNT-ID: $SMARTSUITE_WORKSPACE_ID" \
https://app.smartsuite.com/api/v1/applications/
# Check workspace ID in SmartSuite URL:
# https://app.smartsuite.com/workspace/YOUR_WORKSPACE_ID/...
```
**Expired Token**
- SmartSuite API tokens may expire
- Generate new token in SmartSuite settings
- Update .env file with new token
---
### 3. API Rate Limiting
#### Symptom
```
Error: Rate limit exceeded (429)
```
#### Cause
Too many API requests in short time period
#### Solution
```javascript
// Already handled in smartsuite-client.ts
// Automatic error detection and guidance
// Manual mitigation:
// 1. Reduce request frequency
// 2. Implement exponential backoff
// 3. Use caching for schema/field data
// 4. Batch operations when possible
```
---
### 4. Record Operations Fail Silently
#### Symptom
API returns 200 OK but record not updated
#### Common Causes
**1. Incorrect Field Format - Checklists**
```javascript
// ❌ WRONG - Simple arrays fail silently
{
"checklist_field": ["Item 1", "Item 2"]
}
// ✅ CORRECT - Full SmartDoc structure
{
"checklist_field": {
"doc": [
{"list_items": [
{"text": [{"text": "Item 1", "type": "text"}]},
{"text": [{"text": "Item 2", "type": "text"}]}
]}
]
}
}
```
**2. Wrong Linked Record Format**
```javascript
// ❌ WRONG - Single value
{
"project_id": "uuid-123"
}
// ✅ CORRECT - Always array
{
"project_id": ["uuid-123"]
}
```
**3. Status Field Value Mismatch**
```javascript
// ❌ WRONG - Display label
{
"status": "Active"
}
// ✅ CORRECT - Option code
{
"status": "active"
}
```
**Solution**: Use `smartsuite_intelligent` tool to validate formats before execution
---
### 5. Filter Operations Return No Results
#### Symptom
```javascript
// Search returns 0 results but records exist
{"operation": "search", "filters": {...}}
```
#### Common Causes
**1. Wrong Operator for Linked Records**
```javascript
// ❌ WRONG - "is" operator fails silently
{
"filters": {
"operator": "and",
"fields": [
{"field": "project_id", "comparison": "is", "value": "uuid-123"}
]
}
}
// ✅ CORRECT - Use "has_any_of"
{
"filters": {
"operator": "and",
"fields": [
{"field": "project_id", "comparison": "has_any_of", "value": ["uuid-123"]}
]
}
}
```
**2. Simple Object Format Instead of Structured**
```javascript
// ❌ WRONG - Simple object format
{
"filters": {"eavcode": "EAV001"}
}
// ✅ CORRECT - Structured format
{
"filters": {
"operator": "and",
"fields": [
{"field": "eavcode", "comparison": "is", "value": "EAV001"}
]
}
}
```
**Solution**: See [config/knowledge/patterns/green/filtering.json](../config/knowledge/patterns/green/filtering.json)
---
### 6. Field Discovery Issues
#### Symptom
```
Cannot find field "projectName" in table
```
#### Cause
Field mappings not configured or field doesn't exist
#### Solution
```bash
# 1. Discover available fields
npm run discover-fields -- --table-id=YOUR_TABLE_ID
# 2. Check field mappings
ls config/field-mappings/
# 3. Create or update field mappings
# Copy from examples:
cp config/field-mappings/examples/projects.yaml config/field-mappings/projects.yaml
# 4. Use smartsuite_discover tool
# In MCP: use smartsuite_discover with operation="fields"
```
---
### 7. Schema/Field Operations Corrupt UUIDs
#### Symptom
```
After updating select field choices, all record values reset
```
#### Cause
**CRITICAL**: Using "options" instead of "choices" or providing incomplete choices array
#### Solution
```javascript
// ❌ WRONG - Missing existing UUIDs
{
"updates": {
"params": {
"choices": [
{"value": "new_status", "label": "New Status"}
]
}
}
}
// ✅ CORRECT - Preserve existing UUIDs
{
"updates": {
"params": {
"choices": [
{"value": "active", "label": "Active", "id": "existing-uuid-1"},
{"value": "inactive", "label": "Inactive", "id": "existing-uuid-2"},
{"value": "new_status", "label": "New Status"} // Only new lacks UUID
]
}
}
}
```
**Prevention**: Always use dry_run=true first, use smartsuite_intelligent tool
---
### 8. MCP Context Window Overflow
#### Symptom
```
Claude: "I apologize, but the response was too large..."
```
#### Cause
Returning too many records in single query
#### Solution
```javascript
// Use smaller limits
{
"operation": "list",
"tableId": "...",
"limit": 5 // Default, increases to 25 cautiously
}
// Use count first to assess size
{
"operation": "count",
"tableId": "...",
"filters": {...}
}
// Implement pagination
{
"operation": "list",
"limit": 10,
"offset": 0 // Then 10, 20, 30, etc.
}
// Use summary mode for schema
{
"tableId": "...",
"outputMode": "summary" // Not "detailed"
}
```
---
### 9. Build Failures
#### Symptom
```
npm run build
ERROR: Cannot find module...
```
#### Solutions
**TypeScript Errors**
```bash
# Check for type errors
npm run typecheck
# Clean and rebuild
npm run clean
npm install
npm run build
```
**Missing Dependencies**
```bash
# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install
# Check for peer dependency issues
npm ls
```
**Outdated Dependencies**
```bash
# Update compatible versions
npm update
# Check for outdated packages
npm outdated
# Audit security issues
npm audit fix
```
---
### 10. Test Failures
#### Symptom
```
npm test
FAIL test/unit/...
```
#### Common Causes
**Environment Variables Missing**
```bash
# Tests require test environment
cp .env.example .env.test
# Set test-specific values
SMARTSUITE_WORKSPACE_ID=test-workspace-id
```
**Test Isolation Issues**
```bash
# Run tests in sequence (not parallel)
npm test -- --no-threads
# Run specific test file
npm test -- test/unit/core/smartsuite-client.test.ts
```
**Memory Leak Warnings**
```
MaxListenersExceededWarning: 11 uncaughtException listeners
```
- Known issue in signal handler tests
- Does not affect production
- Fix in progress (see GitHub issues)
---
### 11. Docker Issues
#### Container Won't Start
```bash
# Check logs
docker logs smartsuite-mcp
# Verify environment variables
docker exec smartsuite-mcp env | grep SMARTSUITE
# Test with interactive mode
docker run -it --rm \
-e SMARTSUITE_API_KEY=$SMARTSUITE_API_KEY \
-e SMARTSUITE_WORKSPACE_ID=$SMARTSUITE_WORKSPACE_ID \
smartsuite-mcp:latest
```
#### Build Failures
```bash
# Clean Docker cache
docker builder prune -a
# Rebuild without cache
docker build --no-cache -t smartsuite-mcp:latest .
# Check Dockerfile syntax
docker build --dry-run .
```
---
### 12. Claude Desktop Integration Issues
#### Server Not Listed in Claude Desktop
**1. Check Configuration Path**
```bash
# macOS
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
# Linux
cat ~/.config/Claude/claude_desktop_config.json
# Windows
type %APPDATA%\Claude\claude_desktop_config.json
```
**2. Verify Configuration Syntax**
```json
{
"mcpServers": {
"smartsuite": {
"command": "node",
"args": ["/ABSOLUTE/PATH/to/smartsuite-mcp/build/src/index.js"],
"env": {
"SMARTSUITE_API_KEY": "your-key",
"SMARTSUITE_WORKSPACE_ID": "your-workspace"
}
}
}
}
```
**3. Restart Claude Desktop**
- Completely quit Claude Desktop
- Restart application
- Check MCP servers in settings
**4. Check Logs**
```bash
# Claude Desktop logs location (macOS)
~/Library/Logs/Claude/
# Look for MCP connection errors
grep "smartsuite" ~/Library/Logs/Claude/*.log
```
---
## Debugging Tools
### Enable Debug Logging
```bash
# Set debug mode
DEBUG=true LOG_LEVEL=debug npm start
# Or in .env
DEBUG=true
LOG_LEVEL=debug
```
### Validate Configuration
```bash
# Test server startup
MCP_VALIDATE_AND_EXIT=true npm start
# Should output:
# SmartSuite MCP Server started
# (then exit immediately)
```
### Test API Connectivity
```bash
# Run health check script
npm run health-check
# Manual API test
curl -v \
-H "Authorization: Token $SMARTSUITE_API_KEY" \
-H "ACCOUNT-ID: $SMARTSUITE_WORKSPACE_ID" \
-H "Content-Type: application/json" \
https://app.smartsuite.com/api/v1/applications/
```
### Inspect Knowledge Base
```bash
# Verify pattern loading
cat config/knowledge/manifest.json
# Check specific patterns
cat config/knowledge/patterns/red/uuid-corruption.json
cat config/knowledge/patterns/green/filtering.json
```
---
## Performance Issues
### High Memory Usage
```bash
# Monitor memory
top -p $(pgrep -f "build/src/index.js")
# Increase Node memory limit
NODE_OPTIONS="--max-old-space-size=2048" npm start
# Check for memory leaks
node --inspect build/src/index.js
# Then use Chrome DevTools
```
### Slow API Responses
```bash
# Enable timing logs
DEBUG=true npm start
# Check SmartSuite API status
curl -w "\nTime: %{time_total}s\n" \
-H "Authorization: Token $SMARTSUITE_API_KEY" \
-H "ACCOUNT-ID: $SMARTSUITE_WORKSPACE_ID" \
https://app.smartsuite.com/api/v1/applications/
# Use caching for repeated queries
# (Schema caching already implemented)
```
---
## Getting Help
### Before Requesting Support
1. ✅ Check this troubleshooting guide
2. ✅ Review [API documentation](./API.md)
3. ✅ Run quality gates: `npm run quality-gates`
4. ✅ Enable debug logging
5. ✅ Collect error messages and logs
### Support Channels
- **Documentation**: [docs/](../README.md)
- **GitHub Issues**: Report bugs and request features
- **Security Issues**: See [SECURITY.md](../SECURITY.md)
### Include in Support Requests
```bash
# System info
node --version
npm --version
uname -a
# Package info
cat package.json | grep version
# Error logs (redact sensitive data!)
npm start 2>&1 | grep -i error
# Test results
npm run quality-gates
```
---
## Reference
- **API Reference**: [docs/API.md](./API.md)
- **Deployment Guide**: [docs/DEPLOYMENT.md](./DEPLOYMENT.md)
- **Architecture**: [docs/001-ARCHITECTURE.md](./001-ARCHITECTURE.md)
- **Knowledge Base**: [config/knowledge/](../config/knowledge/)
- **SmartSuite Truth**: [coordination/smartsuite-truth/](../coordination/smartsuite-truth/)
---
**Version**: 1.0.0
**Last Updated**: 2025-11-11
