Skip to main content

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.

OPA showing Browser Unreachable status

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:

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

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

ENOTFOUNDDNS 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.
ECONNREFUSEDIndicates 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.
ECONNRESETIndicates 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.
400This 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.
408Requests 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.
500This 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

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.
503Your 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 errorsSee Troubleshooting CORS issues section below.
Certificate errorsMake 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:

Example values to add to proxy or service mesh config:

allowCredentials: true
- exact:
- exact:
- x-superblocks-request-id
- authorization
- content-type


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.

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.


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