Common issues
This page provides solutions to frequently encountered problems when using the Developer SDK.
Connection issues
”Connection refused” on localhost
Symptoms: ConnectionError: Connection refused to localhost:3000
Cause: Aerospike server is not running or is listening on a different port.
Solution:
import com.aerospike.client.sdk.Cluster;import com.aerospike.client.sdk.ClusterDefinition;
// Verify the server is running// Check that port 3000 is accessibleCluster cluster = new ClusterDefinition("127.0.0.1", 3000) // Try explicit IP .connect();from aerospike_sdk import ClusterDefinition
# Verify the server is running# Check that port 3000 is accessiblecluster = await ClusterDefinition("127.0.0.1", 3000).connect()“Cluster not found” with multiple hosts
Symptoms: Client cannot discover the cluster despite providing seed hosts.
Cause: Network partition, DNS issues, or firewall blocking cluster discovery.
Solution: Ensure all cluster nodes are reachable and ports 3000-3002 are open.
Query issues
DSL query returns empty results
Symptoms: Query executes without error but returns no records.
Cause: Missing secondary index, wrong bin name, or no matching data.
Solution:
- Verify the secondary index exists on the bin you’re querying
- Check that bin names match exactly (case-sensitive)
- Confirm records exist that match your filter
Performance issues
High latency on reads
Symptoms: Read operations taking longer than expected (>10ms).
Cause: Network latency, server load, or suboptimal Behavior configuration.
Solution:
- Check network latency to the cluster
- Review server metrics for load issues
- Consider using
Behavior.READ_FASTfor read-heavy flows