# 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](https://github.com/aerospike/voyager/issues) (see [Feedback and bug reports](#feedback-and-bug-reports) below) or check the [Aerospike community forums](https://discuss.aerospike.com/). ## 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](https://aerospike.com/docs/database/tools/voyager/quickstart#3-load-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. ![MCP Server Statistics tab showing Current session metrics (Requests, Errors, Uptime, Last activity) and a per-tool table with Requests, Errors, Blocked, and Avg latency columns](https://aerospike.com/docs/_astro/mcp_statistics.BSghy8qj_1Y3mlA.png) ### 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](https://aerospike.com/docs/database/tools/voyager/mcp/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](https://aerospike.com/docs/database/tools/voyager/mcp/) or use an [Aerospike client SDK](https://aerospike.com/docs/develop/client-matrix) 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](https://github.com/aerospike/voyager/issues). 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.