Troubleshooting

Common issues and how to resolve them.

Collect Diagnostics

Before diving into specific issues, run mcpctl diag to collect a complete diagnostic bundle. This command gathers agent logs, configuration (with secrets redacted), scan history, trust service connectivity results, and system information into a single archive and uploads it to a secure location.

mcpctl diag

On completion, the command prints a retrieval URL that you can share with Truvant support. The bundle is retained for 7 days and is accessible only to you and the Truvant support team.

Common Issues

Policy not enforcing

If you have configured a policy role but commands are not being blocked as expected, work through the following checks in order:

  1. Check agent status. Run mcpctl status and confirm the agent is listed as running. If it shows stopped or error, start it with mcpctl start.
  2. Check the policy role mode. In the Trust Dashboard, navigate to Policy Management and confirm that the role assigned to this host is set to Enforce, not Monitor. In Monitor mode, violations are logged but commands are never blocked.
  3. Restart your shell. The mcpctl shim is activated at shell startup. If the agent was installed or updated during your current session, open a new terminal window to ensure the shim is active.
  4. Test a command from the dashboard. On the Host Detail page for this machine, use the Test Command feature to simulate a command against the active policy. This isolates whether the policy is correctly configured or whether the issue is with shim activation.

Agent not connecting to trust service

If mcpctl status shows the trust service as unreachable or the agent cannot sync policy updates, check the following:

  1. Check agent status. Run mcpctl status and look for a trust_service connectivity field. A disconnected state indicates a network or authentication issue.
  2. Check your authentication token. Run mcpctl login to re-authenticate. Tokens expire after 24 hours by default. If login fails, check that your identity provider is reachable.
  3. Check network access. Verify that the machine can reach trust.truvant.ai on port 443. Run curl -sv https://trust.truvant.ai/health and confirm a 200 OK response.
  4. Check proxy and firewall rules. If your organization routes outbound HTTPS through a proxy, set the HTTPS_PROXY environment variable before starting the agent. If a firewall or DLP solution performs TLS inspection, add trust.truvant.ai to its bypass list.
Offline fallback If the trust service is unreachable, the agent continues to enforce policy using the last successfully synced policy and cached trust scores. Local scanning is unaffected by trust service connectivity.

Scan results not appearing in dashboard

If you have run mcpctl scan but the results are not visible in the Trust Dashboard, check the following:

  1. Check authentication. Scan results are only imported if you are authenticated. Run mcpctl login to confirm your session is active.
  2. Check the --no-import flag. If you ran mcpctl scan --no-import, results were intentionally not sent to the dashboard. Rerun without that flag to import results.
  3. Check that the agent is running. The agent is responsible for forwarding scan results to the trust service. Run mcpctl status and confirm it is running.
  4. Verify this host appears on the Hosts page. Open the Trust Dashboard and navigate to the Hosts page. If this machine is not listed, the agent has not yet successfully registered. Run mcpctl install to re-register, or check the agent logs with mcpctl diag.

Agent won't start

If mcpctl start exits immediately or the agent fails to stay running, check the following:

  1. Check for another running instance. Run mcpctl status. If another instance is already running, stop it with mcpctl stop before starting again. Multiple agent instances on the same machine are not supported.
  2. Check system logs. Examine the system log for error messages from the agent process:
    • Linux: journalctl -u mcpctl --since "10 minutes ago"
    • macOS: log show --predicate 'process == "mcpctl"' --last 10m
  3. Try reinstalling. If the logs show a corrupted binary or missing dependency, reinstall the agent: mcpctl uninstall && mcpctl install. This preserves your configuration and policy assignments.

Commands being incorrectly blocked

If legitimate commands are being blocked by policy, use the following steps to diagnose and adjust the policy without disabling enforcement entirely:

  1. Use the Test Command feature. On the Host Detail page for this machine, enter the blocked command in the Test Command field. The dashboard shows exactly which policy rule matched and why the command was denied.
  2. Check the Audit Log. In the Audit Log, filter by this host and look for the blocked event. The log entry includes the matched rule name, the artifact involved, and the trust score that triggered the block.
  3. Edit the policy role. If the block is a false positive, navigate to the matched rule in Policy Management and adjust the rule's threshold, add an exception for the specific artifact, or move the artifact to a higher-trust tier.
  4. Switch to Monitor mode temporarily. If you need to unblock commands immediately while you investigate, set the policy role to Monitor mode. Violations will continue to be logged, but no commands will be blocked. Remember to switch back to Enforce once the policy is corrected.

Get Help

If the steps above do not resolve your issue, the Truvant support team is here to help.