Troubleshooting

This guide helps you diagnose and fix common connection issues with CloudSignal. Use it when a client refuses to connect, gets disconnected, or fails to publish or subscribe.

Quick diagnostic

Start here for any connection problem:

1. Check credentials, is the username format correct? (user@org-id)
2. Verify TLS, are you connecting to port 8883 with SSL enabled?
3. Test with MQTTX, can you connect with a known-good client?
4. Check dashboard, do you see the session in active sessions?

Common issues

"Connection refused"

Symptoms:

• Client immediately fails to connect
• Error code: CONNACK return code not 0

Causes and solutions:

"Not authorized" / "Bad username or password"

Symptoms:

• Connection attempt rejected
• Auth error in logs

Check these in order:

1. Username format

   Wrong: agent-001
   Wrong: agent-001@
   Correct: agent-001@a1b2c3d4-e5f6-7890-abcd-ef1234567890

2. Organization ID

   • Go to Settings then Organization in dashboard
   • Copy the exact organization ID
   • Ensure no extra spaces or characters

3. Password

   • Passwords are case-sensitive
   • No leading/trailing spaces
   • If forgotten, reset in MQTT Users

4. User exists

   • Check MQTT Users in dashboard
   • Verify the username is listed

"Connection lost" / frequent disconnections

Symptoms:

• Client connects then disconnects
• Intermittent connectivity
• Keep-alive timeouts

Causes and solutions:

Recommended keep-alive settings:

"ACL denied" / cannot publish or subscribe

Symptoms:

• Connected successfully
• Publish or subscribe fails silently
• Messages not received

Debugging steps:

1. Check ACL rules

   • Go to ACL Rules in dashboard
   • Find rules for your username
   • Verify topic pattern matches

2. Verify topic exactly

   ACL allows: agents/+/state
   
   Works: agents/agent-001/state
   Fails: agents/state (missing level)
   Fails: Agents/agent-001/state (case mismatch)

3. Check permission type

   • publish allows sending only
   • subscribe allows receiving only
   • pubsub allows both

"Client identifier already in use"

Symptoms:

• New connection succeeds
• Old connection disconnected
• "Takeover" in session history

Cause: Two clients using the same client ID

Solutions:

• Use unique client IDs for each instance
• If intentional, only one connection can be active

// Generate unique client ID
const clientId = `agent-001-${Date.now()}`;
// or
const clientId = `agent-001-${uuid()}`;

"Connection timeout"

Symptoms:

• Client hangs trying to connect
• Eventually times out

Causes and solutions:

Test DNS and connectivity:

# Test DNS
nslookup mqtt.cloudsignal.app

# Test port connectivity
nc -zv mqtt.cloudsignal.app 8883

# Test with OpenSSL
openssl s_client -connect mqtt.cloudsignal.app:8883

Messages not received

Symptoms:

• Subscriber connected
• Publisher publishing
• No messages arriving

Debugging steps:

1. Verify both connected

   • Check active sessions for both clients

2. Check topics match exactly

   Publisher: agents/agent-001/state
   Subscriber: agents/agent-001/status  <- Doesn't match

3. Check QoS levels

   • Publisher QoS 0 + unstable network = messages lost
   • Try QoS 1 for reliability

4. Check ACL for both

   • Publisher needs publish permission
   • Subscriber needs subscribe permission

5. Check subscription timing

   • Subscriber must subscribe before publisher publishes
   • Unless using retained messages

TLS/SSL errors

Symptoms:

• "SSL handshake failed"
• "Certificate verification failed"
• "Unknown CA"

Solutions:

// Node.js - Trust the certificate
const client = mqtt.connect('mqtts://mqtt.cloudsignal.app:8883', {
  username: 'user@org-id',
  password: 'password',
  rejectUnauthorized: true  // Keep true for security
});

# Python - Use system CA certificates
import ssl
client.tls_set(cert_reqs=ssl.CERT_REQUIRED)

If using self-signed certificates (development only):

// Not recommended for production
rejectUnauthorized: false

CloudSignal SDK issues

If you're using the @cloudsignal/mqtt-client SDK, here are common issues and solutions.

Infinite reconnect loop

Symptoms:

• SDK keeps trying to reconnect even after auth failure
• Console shows repeated connection attempts
• App performance degrades

Cause: Prior to v2.2.0, the SDK would infinitely retry on authentication errors.

Solution: Upgrade to v2.2.0+ which stops reconnect on auth errors by default:

npm update @cloudsignal/mqtt-client

Or explicitly configure auth retry behavior:

const client = new CloudSignal({
  tokenServiceUrl: 'https://auth.cloudsignal.app',
  reconnectOnAuthError: false, // Default in v2.2.0+
  maxAuthRetries: 0,           // Don't retry auth errors
});

React StrictMode double connection

Symptoms:

• Two connections appear in active sessions
• "Client identifier already in use" errors
• Connection immediately drops after connecting

Cause: React StrictMode (enabled by default in development) mounts components twice to detect side effects.

Solution: Use refs to prevent duplicate connections:

const clientRef = useRef(null);
const connectingRef = useRef(false);
const mountedRef = useRef(true);

const connect = useCallback(async (config) => {
  // Guard against double-connect
  if (connectingRef.current || clientRef.current) return;
  connectingRef.current = true;

  try {
    const client = new CloudSignal({ /* options */ });
    await client.connectWithToken(config);

    // Check if still mounted
    if (!mountedRef.current) {
      client.destroy();
      return;
    }

    clientRef.current = client;
  } finally {
    connectingRef.current = false;
  }
}, []);

useEffect(() => {
  mountedRef.current = true;
  return () => {
    mountedRef.current = false;
    clientRef.current?.destroy();
  };
}, []);

Token expiry / auth errors

Symptoms:

• onAuthError callback fires
• "Bad username or password" error
• Connection drops after token expires

Causes:

1. External IdP token expired
2. Secret key is invalid
3. Organization ID is incorrect

Solutions:

1. For external IdP auth (Supabase/Firebase): Listen for token refresh:

// Supabase example
supabase.auth.onAuthStateChange((event, session) => {
  if (event === 'TOKEN_REFRESHED') {
    // Reconnect with new token
    disconnect();
    setTimeout(() => connect(), 100);
  }
});

2. Handle auth errors gracefully:

client.onAuthError = (error) => {
  console.error('Auth failed:', error.message);
  // Show login prompt, refresh token, or redirect
};

3. Verify credentials:
   • Check organizationId matches your dashboard settings
   • Ensure secretKey is valid (check Settings then API Keys)
   • Verify external token hasn't expired

idToken vs externalToken parameter

Symptoms:

• Documentation shows idToken but code doesn't work
• "externalToken" validation errors

Solution: Both idToken and externalToken are supported (they're aliases). Use externalToken for new code:

// Both work in v2.2.0+
await client.connectWithToken({
  host: 'wss://connect.cloudsignal.app:18885/',
  organizationId: 'your-org-uuid',
  externalToken: session.access_token,  // Preferred
  // idToken: session.access_token,     // Also works (legacy)
});

Debug mode

Enable debug logging to diagnose issues:

const client = new CloudSignal({
  debug: true,  // Logs connection events to console
  tokenServiceUrl: 'https://auth.cloudsignal.app',
});

This will log:

• Token exchanges
• Connection state changes
• Reconnection attempts
• Auth errors with details

Testing tools

MQTTX (recommended)

GUI client for testing connections:

1. Download from mqttx.app
2. Create connection:
   • Host: mqtt.cloudsignal.app
   • Port: 8883
   • Username: user@org-id
   • Password: Your password
   • SSL: Enabled

Mosquitto CLI

Command-line testing:

# Subscribe
mosquitto_sub -h mqtt.cloudsignal.app -p 8883 \
  -u "user@org-id" -P "password" \
  --capath /etc/ssl/certs \
  -t "test/topic"

# Publish
mosquitto_pub -h mqtt.cloudsignal.app -p 8883 \
  -u "user@org-id" -P "password" \
  --capath /etc/ssl/certs \
  -t "test/topic" -m "Hello"

Check from dashboard

Getting help

If you've tried the above and still have issues:

1. Gather information:

   • Error message (exact text)
   • Client library and version
   • Username (not password)
   • Topic you're trying to access

2. Check status page:

   • Visit status.cloudsignal.io for service status

3. Contact support:

   • Email: support@cloudsignal.io
   • Include the information gathered above

Next steps

• Active sessions - Check connection status
• Session history - Review past connections
• Username format - Ensure correct credentials
• ACL rules - Verify permissions