# Common issues

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

::: coming soon
This page is under development. Content will include:

-   Connection troubleshooting
-   Query issues and solutions
-   Performance problems
-   Configuration mistakes
:::

## 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**:

-   [Java](#tab-panel-3058)
-   [Python](#tab-panel-3059)

```java
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();
```

```python
from aerospike_sdk import ClusterDefinition

# Verify the server is running

# Check that port 3000 is accessible

cluster = 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**:

1.  Verify the secondary index exists on the bin you’re querying
2.  Check that bin names match exactly (case-sensitive)
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 using `Behavior.READ_FAST` for read-heavy flows

---

## Next steps

-   [Error Codes Reference](https://aerospike.com/docs/develop/client/sdk/reference/error-codes)
-   [Known Issues](https://aerospike.com/docs/develop/client/sdk/reference/known-issues)
-   [Troubleshooting Connection Issues](https://aerospike.com/docs/develop/client/sdk/connect#troubleshooting)