Skip to main content

Troubleshooting

Common issues and solutions when working with Swarm AI.

Claude Desktop / Claude Code​

Tools Not Appearing​

Symptoms: Claude doesn't mention Swarm AI tools or says it can't control devices.

Solutions:

  1. Check your config file - Verify the JSON is valid (no trailing commas):

    {
      "mcpServers": {
        "swarm": {
          "url": "https://swarm.cheshirelabs.io/mcp",
          "transport": "streamable-http",
          "headers": {
            "X-API-Key": "your-api-key-here"
          }
        }
      }
    }

  2. Verify the URL - Must be exactly https://swarm.cheshirelabs.io/mcp

  3. Check your API key - Ensure it's correct and active

  4. Restart Claude - Config changes require a restart

  5. Ask Claude directly:

    "What MCP servers do you have access to?"

Authentication Errors​

Symptoms: Claude says it can't authenticate or API key is invalid.

Solutions:

  1. Double-check your API key (no extra spaces or characters)
  2. Ensure the key is in the headers section, not at the top level
  3. Contact us if your key may have expired

swarm-client​

Connection Failed​

Symptoms: swarm-client can't connect to Swarm Cloud.

Solutions:

  1. Check network access:

    curl https://swarm.cheshirelabs.io/health

    Should return a success response.

  2. Verify API key - Ensure SWARM_API_KEY environment variable is set

  3. Check firewall - Ensure outbound HTTPS (443) is allowed

  4. Review logs - swarm-client logs show connection details

Device Not Connecting​

Symptoms: Device doesn't appear in swarm-client startup or device list.

Solutions:

  1. Check physical connection:

    • USB cable connected?
    • Device powered on?
    • Status lights normal?

  2. Verify port/address:

    • For USB: Check the port (COM3, /dev/ttyUSB0, etc.)
    • For network: Ping the device IP

  3. Check exclusivity:

    • Close any other software using the device
    • Only one process can access a serial port

  4. Review config:

    {
      "device_id": "my-shaker",
      "type": "shaker",
      "driver": "inheco_thermoshake",
      "config": {
        "port": "COM3"
      }
    }

Frequent Disconnections​

Symptoms: swarm-client repeatedly reconnects.

Solutions:

  1. Check network stability - Wired connection recommended
  2. Disable sleep mode - Ensure computer doesn't sleep
  3. Review logs - Look for specific error messages
  4. Check API key - Ensure it hasn't been revoked

Device Operations​

"Device Not Found"​

Symptoms: Claude or API says device doesn't exist.

Solutions:

  1. Check device_id spelling - IDs are case-sensitive
  2. List available devices:

    "What devices are connected to Swarm AI?"

  3. Verify swarm-client is running - Device must be connected

"Device Not Initialized"​

Symptoms: Operation fails because device needs initialization.

Solutions:

  1. Initialize the device:

    "Initialize the shaker"

  2. Wait for completion - Initialization can take 10-30 seconds
  3. Check for errors - Some devices fail initialization if busy

Operation Timeout​

Symptoms: Command takes too long and times out.

Solutions:

  1. Check device status - Is it physically responsive?
  2. Try again - Temporary network issues can cause timeouts
  3. Check swarm-client - Ensure it's still running and connected
  4. Reduce operation time - Very long operations may timeout

Operation Failed​

Symptoms: Command returns an error from the device.

Solutions:

  1. Check device state:

    • Door closed? (for centrifuges)
    • Plate present? (for sealers)
    • Not already running?

  2. Check parameters:

    • Speed within range?
    • Temperature valid?
    • Duration reasonable?

  3. Review device-specific errors - Error message often indicates the issue

Transporter Issues​

"Position Not Found"​

Symptoms: Transporter can't find a teachpoint.

Solutions:

  1. List teachpoints:

    "What positions are saved for the robot?"

  2. Check name spelling - Teachpoint names are case-sensitive
  3. Create the position if it doesn't exist

Movement Errors​

Symptoms: Robot won't move to position or errors during movement.

Solutions:

  1. Check for obstructions - Physical obstacles in path?
  2. Verify position is reachable - Within robot's workspace?
  3. Reduce speed - Complex movements may fail at high speed
  4. Re-initialize - After emergency stop, robot needs re-initialization

Teaching Mode Issues​

Symptoms: Can't enable free mode or save positions.

Solutions:

  1. Ensure robot is initialized first
  2. Disable free mode before saving:

    "Disable free mode" "Save current position as new_point"

  3. Check coordinate type - Use cartesian for pick/place positions

REST API​

401 Unauthorized​

Symptoms: API returns 401 error.

Solutions:

  1. Check X-API-Key header is present
  2. Verify API key is correct
  3. Ensure no extra whitespace in key

404 Not Found​

Symptoms: API returns 404 for device operations.

Solutions:

  1. Verify device_id exists
  2. Check endpoint URL is correct
  3. Ensure swarm-client is running with that device

400 Bad Request​

Symptoms: API returns 400 error.

Solutions:

  1. Check request body JSON is valid
  2. Verify all required parameters are present
  3. Ensure parameter values are within valid ranges

Getting Help​

During the beta, we provide direct support:

  1. Contact us with your issue
  2. Include relevant logs and error messages
  3. We'll help diagnose and resolve the issue

For urgent issues with running lab operations, include:

  • Device ID
  • Operation attempted
  • Error message received
  • Time of occurrence