Skip to content
MilvusNode SDK
Sections

Troubleshoot Milvus SDK Errors

Markdown

Copy for agent

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

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.

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

Error: Invalid argument

Solutions:

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

Error: Connection refused or ECONNREFUSED

Solutions:

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

Error: Authentication failed

Solutions:

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

Error: Schema mismatch

Solutions:

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

Symptoms: Connection timeout or refused

Solutions:

  1. Check Milvus Status:
Terminal window
# 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);
}

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
},
});

Symptoms: Search operations are slow

Solutions:

  1. 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
);
  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',
});
}

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',
});

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);

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',
});
const client = new MilvusClient({
address: 'localhost:19530',
logLevel: 'debug', // Enable debug logging
logPrefix: 'milvus-client',
});
const client = new MilvusClient({
address: 'localhost:19530',
trace: true, // Enable detailed tracing
});

Add trace IDs to track specific requests:

// 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 for more details.

const info = await client.describeCollection({
collection_name: 'my_collection',
});
console.log('Schema:', JSON.stringify(info.schema, null, 2));
// Check field types
const info = await client.describeCollection({
collection_name: 'my_collection',
});
info.schema.fields.forEach((field) => {
console.log(`${field.name}: ${field.data_type}`);
});
// Enable logging
const client = new MilvusClient({
address: 'localhost:19530',
logLevel: 'info',
});
// Logs will show:
// - Connection status
// - Request/response details
// - Error messages
  • Connection established: Connected to Milvus
  • Collection created: Collection created successfully
  • Index built: Index build completed
  • Search executed: Search completed

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.