Skip to Content
ReferenceTroubleshooting

Troubleshooting

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

Common Errors and Solutions

CollectionNotExists

Error: Collection my_collection does not exist

Solutions:

  • Check collection name spelling
  • List collections to verify: await client.showCollections()
  • 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:
# Check if Milvus is running
docker ps | grep milvus
  1. Verify Address:
// Ensure address is correct
const client = new MilvusClient({
  address: 'localhost:19530', // Check host and port
});
  1. Check Network:
// 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:
const client = new MilvusClient({
  address: 'milvus.example.com:443',
  ssl: true,
  tls: {
    rootCertPath: '/path/to/ca.pem', // Verify path
    serverName: 'milvus.example.com',
  },
});
  1. 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

Slow Search Performance

Symptoms: Search operations are slow

Solutions:

  1. Check Index:
const index = await client.describeIndex({
  collection_name: 'my_collection',
  field_name: 'vector',
});
 
console.log('Index type:', index.index_type);
  1. 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,
});
  1. 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

Symptoms: High memory consumption

Solutions:

  1. Release Unused Collections:
await client.releaseCollection({
  collection_name: 'unused_collection',
});
  1. Use Memory-Efficient Indexes:
// 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:
await client.insert({
  collection_name: 'my_collection',
  data: [/* ... */],
});
 
// Flush to persist data
await client.flush({
  collection_names: ['my_collection'],
});
  1. Check Collection State:
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:
const info = await client.describeCollection({
  collection_name: 'my_collection',
});
 
console.log('Consistency level:', info.consistency_level);
  1. Use Strong Consistency:
await client.createCollection({
  collection_name: 'my_collection',
  fields: schema,
  consistency_level: 'Strong',
});

Debugging Tips

Enable Debug Logging

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

Enable Trace

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

Use TraceID for Request Tracking

Add trace IDs to track specific requests:

// Add trace ID to track requests
await client.createCollection({
  collection_name: 'my_collection',
  fields: [...],
  client_request_id: 'debug-trace-123', // Track this specific request
});
 
// All operations support trace IDs
await client.insert({
  collection_name: 'my_collection',
  data: [...],
  client_request_id: 'insert-trace-456',
});

This helps correlate logs and errors with specific requests. See Request Tracing for more details.

Check Collection Schema

const info = await client.describeCollection({
  collection_name: 'my_collection',
});
 
console.log('Schema:', JSON.stringify(info.schema, null, 2));

Verify Data Types

// 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

// 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

Community Resources

Provide Information

When reporting issues, include:

  1. SDK Version:
console.log(MilvusClient.sdkInfo);

  1. Milvus Version: Check your Milvus server version

  2. Error Details: Full error message and stack trace

  3. Code Sample: Minimal reproducible example

  4. Environment: Node.js version, OS, etc.

Next Steps

Last updated on
API ReferenceMigration & Compatibility