Voyager troubleshooting

This page covers common Aerospike Voyager issues and their solutions. If your issue is not listed here, file it as a GitHub issue (see Feedback and bug reports below) or check the Aerospike community forums.

Connection issues

Connection refused

The cluster may not be running, or the host and port are incorrect.

• Verify the cluster is running and accepting connections on the configured port (default: 3000).
• Check that no firewall is blocking the port.
• If using Docker, confirm the container port is mapped to the host (for example, -p 3000:3000).

TLS handshake failures

• Verify the certificate has not expired.
• Confirm the certificate matches the hostname or IP you are connecting to.
• Check that the TLS server name in the connection settings matches the certificate’s Common Name or Subject Alternative Name.

Authentication failures

• Verify the username and password are correct.
• Confirm the user exists on the cluster.
• If the cluster does not have security enabled, leave the username and password fields empty.

Platform-specific issues

Windows: SmartScreen warning

Windows SmartScreen may warn that the app is unrecognized. Code signing is not yet implemented for the Preview release.

Click More info, then click Run anyway.

Data browser issues

Empty namespace or set

Data may not be loaded yet. Try loading sample data or verify your application has written data to the expected namespace and set.

Records not appearing

Confirm you are connected to the correct cluster and namespace. If you recently wrote data, click the Refresh button in the records toolbar to refetch from the cluster.

Filter issues

Bin name too long

Aerospike limits bin names to 15 bytes. Rename the bin to 15 bytes or fewer.

MCP server issues

AI agent cannot connect

The MCP server is started automatically when Voyager launches; there is no manual start button. To diagnose connection issues:

1. Open the MCP Server page in Voyager and switch to the Statistics tab. This shows current-session request counts, errors, and per-tool activity. If Requests is 0 and your agent says it cannot connect, the agent is not reaching the server.
2. Confirm the URL in your agent’s configuration matches the endpoint shown on the Settings tab (for example, http://127.0.0.1:9090/mcp for desktop mode).
3. If authentication is configured via the MCP_AUTH_TOKEN environment variable, verify your agent is sending the token as a Bearer credential in the Authorization header.

Tools not available

You may be using the Browse and read only access profile, which blocks write and admin operations. Switch to All tools enabled from the profile selector on the MCP Server page.

Blocked tools still appear in your agent’s tool list; they are rejected at call time with an error that identifies the active profile and the allowed tool set. See the Tool reference for which tools each profile allows.

Connection works but queries fail

The MCP server requires Voyager to have an active cluster connection. Open Voyager and confirm you are connected to a cluster before sending queries through your AI agent. You can also have the agent call list_connections to see the status of each saved connection.

Running Voyager in a container

Voyager is a desktop application and is not supported running inside a Docker container or other headless environment. For programmatic access to an Aerospike cluster, connect an AI agent to Voyager’s MCP server or use an Aerospike client SDK directly.

Auto-update issues

Update check failing

Network restrictions or proxy configuration may prevent Voyager from reaching the update server. Check your network settings and try again.

Debug logging

Enable debug logging in Settings > Advanced > Enable debug logging. Logs are written to a file under the OS temp directory; the full path is shown beneath the toggle once debug logging is enabled. Include these logs when reporting issues.

Feedback and bug reports

File bugs, feature requests, and questions as GitHub issues on the Voyager repository. When reporting a bug, include:

• Voyager version (shown in Settings > About) and your OS.
• Steps to reproduce, expected behavior, and actual behavior.
• The exact wording of any error message shown in the UI.
• Debug logs from the previous section, if the issue is reproducible.