# Troubleshoot Milvus SDK Errors

Diagnose Milvus Node.js SDK failures involving connections, authentication, schema validation, indexes, or search.

SDK: `@zilliz/milvus2-sdk-node@3.0.10` · Tested with Milvus 3.0.6

Canonical documentation: https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/

## Section links

- [Frequently Asked Questions](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#frequently-asked-questions)
- [Which npm package should I use with Milvus 3.0?](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#npm-package-milvus-3)
- [Why does my Milvus search return no results?](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#search-returns-no-results)
- [Should SDK request fields use snake_case or camelCase?](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#snake-case-vs-camelcase)
- [How do I preserve Int64 primary key precision in JavaScript?](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#int64-primary-key-precision)
- [Should I set endpoint or baseURL in a serverless HttpClient?](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#serverless-endpoint-vs-baseurl)
- [Common Errors and Solutions](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#common-errors-and-solutions)
- [CollectionNotExists](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#collectionnotexists)
- [IllegalArgument](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#illegalargument)
- [Connection Errors](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#connection-errors)
- [Authentication Errors](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#authentication-errors)
- [Schema Mismatch](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#schema-mismatch)
- [Connection Issues](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#connection-issues)
- [Cannot Connect to Milvus](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#cannot-connect-to-milvus)
- [SSL/TLS Connection Issues](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#ssltls-connection-issues)
- [Performance Issues](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#performance-issues)
- [Slow Search Performance](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#slow-search-performance)
- [High Memory Usage](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#high-memory-usage)
- [Data Consistency Issues](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#data-consistency-issues)
- [Data Not Appearing After Insert](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#data-not-appearing-after-insert)
- [Inconsistent Query Results](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#inconsistent-query-results)
- [Debugging Tips](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#debugging-tips)
- [Enable Debug Logging](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#enable-debug-logging)
- [Enable Trace](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#enable-trace)
- [Use TraceID for Request Tracking](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#use-traceid-for-request-tracking)
- [Check Collection Schema](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#check-collection-schema)
- [Verify Data Types](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#verify-data-types)
- [Log Analysis](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#log-analysis)
- [Understanding Logs](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#understanding-logs)
- [Common Log Messages](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#common-log-messages)
- [Getting Help](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#getting-help)
- [Check Documentation](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#check-documentation)
- [Community Resources](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#community-resources)
- [Provide Information](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#provide-information)
- [Next Steps](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/#next-steps)

This guide helps you troubleshoot common issues when using the Milvus Node.js SDK.

## Frequently Asked Questions

### Which npm package should I use with Milvus 3.0?

Install @zilliz/milvus2-sdk-node@3. The official Milvus Node.js SDK kept its package name for Milvus 3.0. SDK 3.x also supports core operations on compatible Milvus 2.x deployments and Zilliz Cloud.

### Why does my Milvus search return no results?

Make sure the collection has an index and is loaded on query nodes. In the gRPC SDK, call loadCollection with the collection name and await it so loading can finish before you search. Then check that your filter matches rows, your vector targets the right field, and your consistency level makes recent inserts visible.

### Should SDK request fields use snake_case or camelCase?

Use snake_case for gRPC MilvusClient request fields such as collection_name and output_fields. Use camelCase for the equivalent REST HttpClient fields, collectionName and outputFields.

### How do I preserve Int64 primary key precision in JavaScript?

Use decimal strings for Int64 primary keys that may exceed Number.MAX_SAFE_INTEGER. Keep large IDs as strings end to end. The REST HttpClient defaults to acceptInt64: false, which requests precision-preserving string IDs from Milvus.

### Should I set endpoint or baseURL in a serverless HttpClient?

Set endpoint to the cluster origin, for example https://your-cluster.example.com. HttpClient appends /v2 automatically. If you override baseURL, supply the complete versioned URL ending in /v2 or Milvus REST calls can return 404.

## Common Errors and Solutions

### CollectionNotExists

**Error**: `Collection my_collection does not exist`

**Solutions**:

- Check collection name spelling
- List collections to verify: `await client.listCollections()`
- Ensure you’re using the correct database

### IllegalArgument

**Error**: `Invalid argument`

**Solutions**:

- Check parameter types and values
- Verify schema matches collection definition
- Ensure required fields are provided

### Connection Errors

**Error**: `Connection refused` or `ECONNREFUSED`

**Solutions**:

- Verify Milvus server is running
- Check address and port: `localhost:19530`
- Check firewall settings
- Verify network connectivity

### Authentication Errors

**Error**: `Authentication failed`

**Solutions**:

- Verify username and password
- Check token validity (for Zilliz Cloud)
- Ensure user has necessary permissions

### Schema Mismatch

**Error**: `Schema mismatch`

**Solutions**:

- Verify field names match schema
- Check data types match field definitions
- Ensure vector dimensions are correct

## Connection Issues

### Cannot Connect to Milvus

**Symptoms**: Connection timeout or refused

**Solutions**:

1. **Check Milvus Status**:

```bash
# Check if Milvus is running
docker ps | grep milvus
```

2. **Verify Address**:

```javascript
// Ensure address is correct
const client = new MilvusClient({
  address: 'localhost:19530', // Check host and port
});
```

3. **Check Network**:

```javascript
// Test connectivity
try {
  await client.connectPromise;
  console.log('Connected successfully');
} catch (error) {
  console.error('Connection failed:', error);
}
```

### SSL/TLS Connection Issues

**Symptoms**: SSL handshake errors

**Solutions**:

1. **Verify Certificate**:

```javascript
const client = new MilvusClient({
  address: 'milvus.example.com:443',
  ssl: true,
  tls: {
    rootCertPath: '/path/to/ca.pem', // Verify path
    serverName: 'milvus.example.com',
  },
});
```

2. **Skip Certificate Check** (development only):

```javascript
const client = new MilvusClient({
  address: 'milvus.example.com:443',
  ssl: true,
  tls: {
    skipCertCheck: true, // Not recommended for production
  },
});
```

## Performance Issues

### Slow Search Performance

**Symptoms**: Search operations are slow

**Solutions**:

1. **Check Index**:

```javascript
const index = await client.describeIndex({
  collection_name: 'my_collection',
  field_name: 'vector',
});

const params = index.index_descriptions[0]?.params;
console.log(
  'Index type:',
  params?.find(({ key }) => key === 'index_type')?.value
);
```

2. **Tune Search Parameters**:

```javascript
// Increase nprobe for better recall (slower)
const results = await client.search({
  collection_name: 'my_collection',
  data: [
    /* vector */
  ],
  params: {
    nprobe: 128, // Increase from default
  },
  limit: 10,
});
```

3. **Ensure Collection is Loaded**:

```javascript
const state = await client.getLoadState({
  collection_name: 'my_collection',
});

if (state.state !== 'LoadStateLoaded') {
  await client.loadCollectionSync({
    collection_name: 'my_collection',
  });
}
```

### High Memory Usage

**Symptoms**: High memory consumption

**Solutions**:

1. **Release Unused Collections**:

```javascript
await client.releaseCollection({
  collection_name: 'unused_collection',
});
```

2. **Use Memory-Efficient Indexes**:

```javascript
// Use IVF_SQ8 or IVF_PQ instead of HNSW
await client.createIndex({
  collection_name: 'my_collection',
  field_name: 'vector',
  index_type: 'IVF_SQ8', // More memory-efficient
  metric_type: 'L2',
});
```

## Data Consistency Issues

### Data Not Appearing After Insert

**Symptoms**: Inserted data not found in queries

**Solutions**:

1. **Flush After Insert**:

```javascript
await client.insert({
  collection_name: 'my_collection',
  data: [
    /* ... */
  ],
});

// Flush to persist data
await client.flush({
  collection_names: ['my_collection'],
});
```

2. **Check Collection State**:

```javascript
const state = await client.getLoadState({
  collection_name: 'my_collection',
});

console.log('Load state:', state.state);
```

### Inconsistent Query Results

**Symptoms**: Query results vary between calls

**Solutions**:

1. **Check Consistency Level**:

```javascript
const info = await client.describeCollection({
  collection_name: 'my_collection',
});

console.log('Consistency level:', info.consistency_level);
```

2. **Use Strong Consistency**:

```javascript
await client.createCollection({
  collection_name: 'my_collection',
  fields: schema,
  consistency_level: 'Strong',
});
```

## Debugging Tips

### Enable Debug Logging

```javascript
const client = new MilvusClient({
  address: 'localhost:19530',
  logLevel: 'debug', // Enable debug logging
  logPrefix: 'milvus-client',
});
```

### Enable Trace

```javascript
const client = new MilvusClient({
  address: 'localhost:19530',
  trace: true, // Enable detailed tracing
});
```

### Use TraceID for Request Tracking

Add trace IDs to track specific requests:

```javascript
// Add trace ID to track requests
await client.listCollections({
  client_request_id: 'debug-trace-123', // Track this specific request
});

// All operations support trace IDs
await client.listCollections({
  'client-request-id': 'list-trace-456',
});
```

This helps correlate logs and errors with specific requests. See [Request Tracing](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#request-tracing-traceid) for more details.

### Check Collection Schema

```javascript
const info = await client.describeCollection({
  collection_name: 'my_collection',
});

console.log('Schema:', JSON.stringify(info.schema, null, 2));
```

### Verify Data Types

```javascript
// Check field types
const info = await client.describeCollection({
  collection_name: 'my_collection',
});

info.schema.fields.forEach((field) => {
  console.log(`${field.name}: ${field.data_type}`);
});
```

## Log Analysis

### Understanding Logs

```javascript
// Enable logging
const client = new MilvusClient({
  address: 'localhost:19530',
  logLevel: 'info',
});

// Logs will show:
// - Connection status
// - Request/response details
// - Error messages
```

### Common Log Messages

- **Connection established**: `Connected to Milvus`
- **Collection created**: `Collection created successfully`
- **Index built**: `Index build completed`
- **Search executed**: `Search completed`

## Getting Help

### Check Documentation

- Review [API Reference](https://milvus-io.github.io/milvus-sdk-node/api-reference/)
- Check [Best Practices](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/)
- Read [Examples & Tutorials](https://milvus-io.github.io/milvus-sdk-node/getting-started/examples-tutorials/)

### Community Resources

- [GitHub Issues](https://github.com/milvus-io/milvus-sdk-node/issues)
- [Milvus Community](https://milvus.io/community)
- [Discord](https://discord.gg/milvus)

### Provide Information

When reporting issues, include:

1. **SDK Version**:

```javascript
console.log(MilvusClient.sdkInfo);
```

2. **Milvus Version**: Check your Milvus server version
3. **Error Details**: Full error message and stack trace
4. **Code Sample**: Minimal reproducible example
5. **Environment**: Node.js version, OS, etc.

## Next Steps

- Review [Best Practices](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/)
- Check [API Reference](https://milvus-io.github.io/milvus-sdk-node/api-reference/)
- Explore [Examples & Tutorials](https://milvus-io.github.io/milvus-sdk-node/getting-started/examples-tutorials/)
