Skip to content

Common issues

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

Applies to

  • Aerospike Developer SDK (Java 21+ and Python 3.11+)
  • Aerospike Database 8.2.0 or later, unless a section states otherwise

This page provides solutions to frequently encountered problems when using the Developer SDK.

Connection issues

”Connection refused” on localhost

Symptoms: connect() fails with AerospikeException.Connection (Java) or ConnectionError from aerospike_sdk.exceptions (Python). The message reads Failed to connect to [1] host(s) and names the seed host, for example 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 accessible
Cluster cluster = new ClusterDefinition("127.0.0.1", 3000)  // Try explicit IP
    .connect();

📖 API reference: ClusterDefinition(String,int) | ClusterDefinition.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 every cluster node’s service port (3000 by default) is reachable from the client. Ports 3001 and 3002 carry fabric and heartbeat traffic between nodes and don’t need to be open to clients.

Query issues

AEL query returns empty results

Symptoms: Query executes without error but returns no records.

Cause: Wrong bin name, a type mismatch in the comparison, or no matching data.

Solution:

  1. Check that bin names match exactly (case-sensitive)
  2. Check that compared values have the stored type, for example $.age > 25 doesn’t match an age bin stored as a string
  3. 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:

  1. Check network latency to the cluster
  2. Review server metrics for load issues
  3. Consider a faster-read Behavior for read-heavy flows: Python provides the built-in Behavior.READ_FAST preset, and Java can derive an equivalent with Behavior.DEFAULT.deriveWithChanges(...)

Next steps