Troubleshoot Milvus SDK Errors
This guide helps you troubleshoot common issues when using the Milvus Node.js SDK.
Frequently Asked Questions
Section titled “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
Section titled “Common Errors and Solutions”CollectionNotExists
Section titled “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
Section titled “IllegalArgument”Error: Invalid argument
Solutions:
- Check parameter types and values
- Verify schema matches collection definition
- Ensure required fields are provided
Connection Errors
Section titled “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
Section titled “Authentication Errors”Error: Authentication failed
Solutions:
- Verify username and password
- Check token validity (for Zilliz Cloud)
- Ensure user has necessary permissions
Schema Mismatch
Section titled “Schema Mismatch”Error: Schema mismatch
Solutions:
- Verify field names match schema
- Check data types match field definitions
- Ensure vector dimensions are correct
Connection Issues
Section titled “Connection Issues”Cannot Connect to Milvus
Section titled “Cannot Connect to Milvus”Symptoms: Connection timeout or refused
Solutions:
- Check Milvus Status:
# Check if Milvus is runningdocker ps | grep milvus- Verify Address:
// Ensure address is correctconst client = new MilvusClient({ address: 'localhost:19530', // Check host and port});- Check Network:
// Test connectivitytry { await client.connectPromise; console.log('Connected successfully');} catch (error) { console.error('Connection failed:', error);}SSL/TLS Connection Issues
Section titled “SSL/TLS Connection Issues”Symptoms: SSL handshake errors
Solutions:
- Verify Certificate:
const client = new MilvusClient({ address: 'milvus.example.com:443', ssl: true, tls: { rootCertPath: '/path/to/ca.pem', // Verify path serverName: 'milvus.example.com', },});- Skip Certificate Check (development only):
const client = new MilvusClient({ address: 'milvus.example.com:443', ssl: true, tls: { skipCertCheck: true, // Not recommended for production },});Performance Issues
Section titled “Performance Issues”Slow Search Performance
Section titled “Slow Search Performance”Symptoms: Search operations are slow
Solutions:
- Check Index:
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);- Tune Search Parameters:
// 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,});- Ensure Collection is Loaded:
const state = await client.getLoadState({ collection_name: 'my_collection',});
if (state.state !== 'LoadStateLoaded') { await client.loadCollectionSync({ collection_name: 'my_collection', });}High Memory Usage
Section titled “High Memory Usage”Symptoms: High memory consumption
Solutions:
- Release Unused Collections:
await client.releaseCollection({ collection_name: 'unused_collection',});- Use Memory-Efficient Indexes:
// Use IVF_SQ8 or IVF_PQ instead of HNSWawait client.createIndex({ collection_name: 'my_collection', field_name: 'vector', index_type: 'IVF_SQ8', // More memory-efficient metric_type: 'L2',});Data Consistency Issues
Section titled “Data Consistency Issues”Data Not Appearing After Insert
Section titled “Data Not Appearing After Insert”Symptoms: Inserted data not found in queries
Solutions:
- Flush After Insert:
await client.insert({ collection_name: 'my_collection', data: [ /* ... */ ],});
// Flush to persist dataawait client.flush({ collection_names: ['my_collection'],});- Check Collection State:
const state = await client.getLoadState({ collection_name: 'my_collection',});
console.log('Load state:', state.state);Inconsistent Query Results
Section titled “Inconsistent Query Results”Symptoms: Query results vary between calls
Solutions:
- Check Consistency Level:
const info = await client.describeCollection({ collection_name: 'my_collection',});
console.log('Consistency level:', info.consistency_level);- Use Strong Consistency:
await client.createCollection({ collection_name: 'my_collection', fields: schema, consistency_level: 'Strong',});Debugging Tips
Section titled “Debugging Tips”Enable Debug Logging
Section titled “Enable Debug Logging”const client = new MilvusClient({ address: 'localhost:19530', logLevel: 'debug', // Enable debug logging logPrefix: 'milvus-client',});Enable Trace
Section titled “Enable Trace”const client = new MilvusClient({ address: 'localhost:19530', trace: true, // Enable detailed tracing});Use TraceID for Request Tracking
Section titled “Use TraceID for Request Tracking”Add trace IDs to track specific requests:
// Add trace ID to track requestsawait client.listCollections({ client_request_id: 'debug-trace-123', // Track this specific request});
// All operations support trace IDsawait client.listCollections({ 'client-request-id': 'list-trace-456',});This helps correlate logs and errors with specific requests. See Request Tracing for more details.
Check Collection Schema
Section titled “Check Collection Schema”const info = await client.describeCollection({ collection_name: 'my_collection',});
console.log('Schema:', JSON.stringify(info.schema, null, 2));Verify Data Types
Section titled “Verify Data Types”// Check field typesconst info = await client.describeCollection({ collection_name: 'my_collection',});
info.schema.fields.forEach((field) => { console.log(`${field.name}: ${field.data_type}`);});Log Analysis
Section titled “Log Analysis”Understanding Logs
Section titled “Understanding Logs”// Enable loggingconst client = new MilvusClient({ address: 'localhost:19530', logLevel: 'info',});
// Logs will show:// - Connection status// - Request/response details// - Error messagesCommon Log Messages
Section titled “Common Log Messages”- Connection established:
Connected to Milvus - Collection created:
Collection created successfully - Index built:
Index build completed - Search executed:
Search completed
Getting Help
Section titled “Getting Help”Check Documentation
Section titled “Check Documentation”- Review API Reference
- Check Best Practices
- Read Examples & Tutorials
Community Resources
Section titled “Community Resources”Provide Information
Section titled “Provide Information”When reporting issues, include:
- SDK Version:
console.log(MilvusClient.sdkInfo);-
Milvus Version: Check your Milvus server version
-
Error Details: Full error message and stack trace
-
Code Sample: Minimal reproducible example
-
Environment: Node.js version, OS, etc.
Next Steps
Section titled “Next Steps”- Review Best Practices
- Check API Reference
- Explore Examples & Tutorials