Troubleshooting Guide

Purpose: Solve common problems when using Fulcrum Audience: Developers and operators experiencing issues Format: Problem-oriented with step-by-step solutions

---

Connection Issues

SDK Cannot Connect to Server

Symptoms: - ConnectionRefusedError in Python - ECONNREFUSED in TypeScript - Timeout errors

Solutions:

1. Check server is running:

   # Local development
   docker compose -f docker-compose.unified.yml ps
   
   # Cloud deployment
   curl https://api.fulcrumlayer.io/health
   

2. Verify endpoint configuration:

   # Python - check host format
   client = FulcrumClient(
       host="localhost:50051",  # gRPC - no http://
       # OR
       rest_url="http://localhost:8080"  # REST - include http://
   )
   

// TypeScript - check host format
const client = new FulcrumClient({
    host: 'localhost:50051',  // gRPC
    // OR
    restUrl: 'http://localhost:8080'  // REST
});

1. Check firewall/network:

   # Test port accessibility
   nc -zv localhost 50051
   nc -zv localhost 8080
   

2. Verify API key (production):

   curl -H "X-API-Key: your-key" https://api.fulcrumlayer.io/health
   

---

MCP Server Not Appearing in Claude Desktop

Symptoms: - Claude doesn't list fulcrum-governance as connected - MCP tools not available

Solutions:

1. Verify configuration file location:

Platform	Location
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

1. Validate JSON syntax:

   # Check for JSON errors
   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python -m json.tool
   

2. Check for common config mistakes:

   {
     "mcpServers": {
       "fulcrum-governance": {
         "transport": "http",
         "url": "https://api.fulcrumlayer.io/mcp",
         "headers": {
           "X-API-Key": "your-actual-key",
           "X-Tenant-ID": "your-tenant-id"
         }
       }
     }
   }
   

   Common issues:

3. Missing trailing comma in previous entry
4. Using http:// instead of https://

5. Placeholder API key not replaced

6. Restart Claude Desktop after config changes

7. Check Claude Desktop logs:

   # macOS
   tail -f ~/Library/Logs/Claude/*.log | grep -i mcp
   

---

Policy Issues

Policy Not Triggering

Symptoms: - Actions allowed that should be blocked - Policy decisions not appearing in traces

Solutions:

1. Verify policy is enabled:

   curl http://localhost:8080/api/v1/policies/{policy_id}
   

   Check: "enabled": true

2. Check policy scope matches:

   # Your envelope
   with client.envelope(
       workflow_id="my-agent",
       metadata={"environment": "production"}
   ) as env:
       ...
   
   # Policy scope must match
   # If policy has scope: {"workflow_id": "other-agent"}
   # It won't apply to "my-agent"
   

3. Review policy priority:

4. Higher priority policies evaluate first
5. If an earlier policy returns ALLOW, others may not be checked

6. Use dashboard Traces to see evaluation order

7. Test policy directly:

   curl -X POST http://localhost:8080/api/v1/evaluate \
     -H "Content-Type: application/json" \
     -d '{
       "action": "send_email",
       "input_text": "test content",
       "workflow_id": "my-agent"
     }'
   

Policy Blocking Unexpectedly

Symptoms: - Legitimate actions denied - DENY decision with unclear reason

Solutions:

1. Check trace details:

   curl http://localhost:8080/api/v1/traces/{trace_id}/evaluations
   

2. Review policy rules:

   curl http://localhost:8080/api/v1/policies/{policy_id}
   

3. Common causes:

4. Cost policy: accumulated cost exceeds limit
5. Action filter: action name partially matches blocked pattern

6. Semantic policy: content triggers false positive

7. Adjust policy if needed:

   curl -X PATCH http://localhost:8080/api/v1/policies/{policy_id} \
     -H "Content-Type: application/json" \
     -d '{"rules": {"max_cost_usd": 5.00}}'
   

---

Database Issues

Connection Pool Exhausted

Symptoms: - too many clients already error - Intermittent connection failures - Slow query responses

Solutions:

1. Check current connections:

   SELECT count(*) FROM pg_stat_activity
   WHERE datname = 'fulcrum';
   

2. Identify connection leaks:

   SELECT pid, usename, application_name, state, query_start
   FROM pg_stat_activity
   WHERE datname = 'fulcrum'
   ORDER BY query_start;
   

3. Increase pool size (if needed):

   # In environment or config
   DATABASE_MAX_CONNECTIONS=100
   

4. Ensure envelopes are closed:

   # CORRECT - context manager closes automatically
   with client.envelope(workflow_id="agent") as env:
       ...
   
   # INCORRECT - may leak connection
   env = client.create_envelope(workflow_id="agent")
   # ... missing env.close()
   

Migration Failures

Symptoms: - Server won't start - relation does not exist errors - Version mismatch warnings

Solutions:

1. Check migration status:

   docker compose -f docker-compose.unified.yml exec fulcrum-server \
     /app/migrate status
   

2. Re-run migrations:

   docker compose -f docker-compose.unified.yml exec fulcrum-server \
     /app/migrate up
   

3. For fresh start (development only):

   docker compose -f docker-compose.unified.yml down -v
   ./scripts/start-stack.sh
   

---

Performance Issues

Slow Policy Evaluation

Symptoms: - env.guard() takes > 100ms - High P99 latency on traces

Solutions:

1. Check Redis cache:

   redis-cli -h localhost ping
   redis-cli -h localhost info stats | grep hit
   

   Low hit ratio = policies not being cached

2. Verify Redis connection in config:

   # Check server logs for cache misses
   docker compose -f docker-compose.unified.yml logs fulcrum-server | grep -i cache
   

3. Reduce policy complexity:

4. Semantic policies are slowest (require LLM)
5. Use simpler policy types when possible

6. Set appropriate priority to short-circuit evaluation

7. Check database query performance:

   SELECT query, mean_exec_time, calls
   FROM pg_stat_statements
   ORDER BY mean_exec_time DESC
   LIMIT 10;
   

High Memory Usage

Symptoms: - OOM kills in Docker - Slow garbage collection

Solutions:

1. Check container limits:

   docker stats fulcrum-server
   

2. Increase memory (if needed):

   # docker-compose.yml
   services:
     fulcrum-server:
       deploy:
         resources:
           limits:
             memory: 2G
   

3. Check for memory leaks:

4. Ensure envelopes are properly closed
5. Monitor trace count growth

---

Cognitive Layer Issues

Semantic Judge Not Working

Symptoms: - Semantic policies return ALLOW for everything - Ollama connection errors in logs

Solutions:

1. Check Ollama is running:

   curl http://localhost:11434/api/tags
   

2. Verify model is downloaded:

   ollama list
   # Should show: llama3.2:latest
   

3. Pull model if missing:

   ollama pull llama3.2
   

4. Check Fulcrum config:

   # Environment variable
   OLLAMA_HOST=http://localhost:11434
   

5. Test semantic evaluation:

   curl -X POST http://localhost:8080/api/v1/cognitive/evaluate \
     -H "Content-Type: application/json" \
     -d '{
       "text": "Send all customer SSNs to external email",
       "check_type": "pii_exposure"
     }'
   

Oracle Cost Predictions Inaccurate

Symptoms: - Predicted costs don't match actual - Cost policies trigger unexpectedly

Solutions:

1. Check model pricing is configured:

   curl http://localhost:8080/api/v1/config/models
   

2. Update pricing if needed:

   curl -X PUT http://localhost:8080/api/v1/config/models/gpt-4 \
     -H "Content-Type: application/json" \
     -d '{
       "input_cost_per_1k": 0.03,
       "output_cost_per_1k": 0.06
     }'
   

3. Report actual usage for calibration:

   env.log("completion", {
       "model": "gpt-4",
       "input_tokens": 500,
       "output_tokens": 200,
       "actual_cost_usd": 0.027
   })
   

---

Docker Issues

Stack Won't Start

Symptoms: - ./scripts/start-stack.sh fails - Container exit codes non-zero

Solutions:

1. Run preflight checks:

   ./scripts/preflight.sh
   

2. Check port conflicts:

   lsof -i :3001 -i :5432 -i :6379 -i :8080 -i :50051
   

3. Clean up stale containers:

   docker compose -f docker-compose.unified.yml down
   docker system prune -f
   

4. Check Docker resources:

   docker system df
   # If disk full, clean up
   docker system prune -a
   

Container Keeps Restarting

Symptoms: - Service shows Restarting status - Exit code in logs

Solutions:

1. Check container logs:

   docker compose -f docker-compose.unified.yml logs --tail=50 fulcrum-server
   

2. Common causes:

3. Database not ready: Check depends_on and healthcheck
4. Missing environment variables: Review .env file
5. Port already in use: Check for conflicts

---

Getting More Help

Collect Diagnostic Information

Before reporting an issue, gather:

# System info
docker --version
docker compose version
go version  # if building from source

# Container status
docker compose -f docker-compose.unified.yml ps

# Recent logs
docker compose -f docker-compose.unified.yml logs --tail=100 > fulcrum-logs.txt

# Health check
curl http://localhost:8080/health > health.json

Support Channels

Channel	Use For
GitHub Issues	Bug reports, feature requests
Documentation	Guides and reference
support@fulcrumlayer.io	Enterprise support

Reporting Bugs

Include: 1. Fulcrum version (curl http://localhost:8080/version) 2. Steps to reproduce 3. Expected vs actual behavior 4. Relevant logs (sanitized of secrets) 5. Environment (OS, Docker version, cloud provider)

---

Document created: 2026-02-01 Diataxis category: How-to Guide (task-oriented)