Troubleshooting the OPA

After an agent has been successfully deployed, the OPAs page in app will show a status of "Active." If not, then there may be an issue with the agent's connection to your browser, to the Superblocks Cloud, or both. For non "Active" statuses, see the troubleshooting techniques detailed below.

Browser Unreachable

The Browser Unreachable status can indicate a number of problems with your agent configuration, but generally means there is a network issue between your browser and the Superblocks agent. While the agent can connect to Superblocks Cloud, your browser cannot connect to this agent.

Some quick points to check:

• For non-localhost deployments, confirm that the agent host URL is correct and exposed via HTTPS.
• If a VPN is required to access the agent, check that you're connected to the VPN on your device.
• Check the ingress and firewall configuration on your agent deployment.
• If using the Brave browser, turn off the Shields for the Superblocks site.

To debug this issue in more detail, open the Developer Settings for your browser and navigate to the Network tab. Locate failed requests made to the following endpoints, based on your agent version:

Agent v1.x.x

• GET https://<AGENT_HOST_URL>/health
• POST https://<AGENT_HOST_URL>/v2/execute/stream

Agent v0.x.x

• GET https://<AGENT_HOST_URL>/agent
• POST https://<AGENT_HOST_URL>/agent/v1/apis/execute

Find the error code and message returned. Common network issues and errors include:

Status	Description
ENOTFOUND	DNS lookup failed. Check that the domain you’re using for your agent is registered and you’ve configured a CNAME or ANAME record for any subdomains added to your agent host url. If the domain is registered, double check that there aren’t any spelling errors in the agent host url configured for your agent.
ECONNREFUSED	Indicates that network rules are blocking your browser from accessing the agent. If your agent is deployed in a private network, check that you’re logged into your VPN. If you are logged into your VPN and still seeing this error, have your agent operator check that the ingress rules for your agent’s load balancer or subnets associated with the agent are configured to allow traffic from users within your private network.
ECONNRESET	Indicates that the agent died while trying to serve a request. If you have auto-scaling configured for your agent, this should be self-healing. If your organization is only running a single agent replica, restart the agent. For high-availability we recommend running at least 3 agent replicas. Read more about Scaling and High-Availability Deployments.
400	This status code indicates that the agent is running, but is still starting up. Wait a few minutes and try again. If the agent takes a very long time to start, it may not have enough memory allocated. Increase memory allocated and restart. Read more about minimum provisioning requirements for On-Premise Agents.
408	Requests to the agent are timing out. This can happen when the agent is under-provisioned. Check service health metrics provided by your cloud provider to determine if additional memory or CPU are needed.
500	This status returned by the /agent or /health endpoint usually indicates the agent is restarting. Wait a few seconds and refresh the browser. If this status is returned by the /agent/v1/apis/execute or /agent/v2/execute/stream endpoint, this can indicate your agent is having problems communicating with the Superblocks server. View the logs for your agent to see if errors are being returned when calling https://app.superblocks.com. Check the Superblocks Status page to see if Superblocks is having an incident. If the status page indicates all Superblocks services are operational and the agent logs are showing an ECONNREFUSED error response, check the egress rules for your network to make sure they allow for outbound network calls.
503	Your agent is running, but requests to the agent are failing. Open the logs for your agent and review any error logs. This can occur when your agent is maxing out its allocated CPU or Memory. If this is the case, provision additional CPU or memory.
CORS errors	See Troubleshooting CORS issues section below.
Certificate errors	Make sure the certificate issued for your agent domain hasn't expired. It is recommended to automate the renewal process if possible. Some examples include AWS Certificate Manager, Traefik with LetsEncrypt (used in VM deployment) and Kubernetes cert-manager.

Troubleshooting CORS issues

If you are using a proxy or service mesh in your agent deployment, check if it's populating the following CORS headers properly:

• Access-Control-Allow-Credentials
• Access-Control-Allow-Headers
• Access-Control-Allow-Methods
• Access-Control-Allow-Origin

Example values to add to proxy or service mesh config:

corsPolicy:
  allowCredentials: true
  allowMethods:
    - GET
    - HEAD
    - PUT
    - PATCH
    - POST
    - DELETE
  allowOrigins:
    - exact: https://app.superblocks.com/
    - exact: https://app.superblockshq.com/
  allowHeaders:
    - x-superblocks-request-id
    - authorization
    - content-type

Disconnected

This status means the agent cannot connect to Superblocks Cloud. Click the agent status in the OPAs page to see more details. If the modal shows that your browser can connect to this agent, then check the egress and firewall configuration on your agent deployment to see if something is preventing it from reaching out to Superblocks.

If the modal shows that your browser cannot connect to this agent, then start by making sure your agent service is running and healthy. For example, kubectl get pods -n superblocks to check if the agent pods are running in Kubernetes, or docker ps | grep superblocks for a Docker deployment. Further inspect the logs/events for these services if they are not healthy.

Agent not appearing on OPA page

This occurs due to similar issues as the Disconnected error. The agent is unable to reach the Superblocks control plane or edge cache to register itself. This error can also be caused by the agent being in an unhealthy state as well. The best way to troubleshoot this issue is to verify that the network does not impede the agent and that the agent is healthy. Run nc -v -w 1 api.superblocks.com 443 from your agent environment and run curl -s -L agent.superblocks.com/health | jq from your local environment.

1. Check Superblocks can reach control plane or edge cache(run this on the agent environment):

If this is occurring, make sure there is a point of egress from the Agent to Superblocks Cloud.

1. Check Agent is healthy(run this locally):

If this is occurring, make sure that there is a point of ingress from your client machines to the On Premise Agent.

Queries timing out

If an agent connection times out from something upstream (for instance, an ELB) you may receive an error that says "Failed to connect to the agents". To fix this, ensure that the timeout set on the ELB is large enough to accommodate the queries that your applications are making. To confirm that this is the case, follow the troubleshooting steps outlined here.

info

Contact Support if you have any questions or need help troubleshooting the OPA.