A Cursor status check usually starts with the same symptom. The agent panel sits on a planning message, the chat reports that a response is taking longer than expected, and nothing streams. Most developers open the vendor status page, see green, and start guessing. Green only proves that Cursor’s servers are up. It says nothing about your DNS resolver, your corporate proxy, or the VPN you disconnected ten minutes ago.
The cost of guessing is climbing because the habit is mainstream. Stack Overflow’s 2025 developer survey press release reports that “31% of developers currently use AI agents, while 17% plan to use them.” When roughly three in ten developers lean on an editor-hosted agent, an hour of connection trouble is an hour of lost output, and nobody on the team can say whether to blame Cursor, the network, or the laptop.
A repeatable probe settles the question in about 12 seconds. cursor-doctor is a single-file Python 3.12 script with no third-party packages. It resolves every host Cursor documents, reads the TLS issuer, replays the two streaming tests from Cursor’s own network docs, and then checks proxy variables, the cursor command, and your ignore files. When a check fails, it points at one of three layers (Cursor’s servers, the path to them, or your machine), and each fix maps to a documented setting. The same probe applies if you run the Cursor CLI from a terminal, because Cursor’s network docs say agents started from the editor or the CLI inherit the network configuration of the machine they run on.
Don't miss new tech stories on Google
Add Shattered once in the Google app and our stories show up in your news suggestions.
Why a Cursor Status Check Beats Refreshing the Status Page #
Cursor’s help pages end with a Check system status link, and that page answers one question: is something broken on Cursor’s side for everyone? When we loaded status.cursor.com on November 20, it rendered a SpaceXSI Status page with Overview and History tabs. Treat it as the first 30 seconds of triage. If it shows an incident, stop debugging and wait. If it shows green, the problem sits somewhere between your keyboard and Cursor’s edge, and the status page cannot see that part.
Provider-side trouble does happen. Cursor’s November 13 security incident update said the company temporarily disabled internal and product services well beyond what the evidence required, which briefly disrupted certain features, and that each one came back once it was safe. That kind of outage belongs on a status page. Local trouble does not, and local trouble causes most of the tickets that start with a colleague saying it works on their machine.
Three layers explain nearly every connection failure, and a good probe separates them:
- Cursor’s side. An outage, a degraded service, or a rollout in progress. The status page covers it.
- The path. DNS, a corporate proxy, TLS inspection, a secure web gateway that buffers streams, or a VPN that left stale resolver settings behind.
- Your machine. An extension host that fails to start, endpoint security software that blocks a process, oversized folders that Cursor tries to index, or a wrong proxy variable in one shell.
Each layer leaves a different fingerprint. A buffering proxy shows up as a streaming test that delivers every chunk at once after five seconds. TLS inspection shows up as a certificate issuer that is not the one Cursor documents. A stale VPN resolver shows up as DNS failures on hosts that resolve fine on your phone. An extension problem shows up as a green network and a red Agent Execution Timed Out banner. Once you can tell these apart in under a minute, the conversation with your IT team changes from a vague complaint that Cursor is broken to a precise finding that api2.cursor.sh returns a certificate issued by your own proxy, which is a ticket someone can actually close.
The probe also helps with cloud-side features. Browser-based agents depend on cursor.com, a different host family from the desktop app, which is why a gateway can break one and leave the other alone. If you build or monitor Cursor Cloud Agents, that split matters more than any single setting.
Prerequisites and Versions for the Cursor Status Probe #
The tool uses only the Python standard library plus the system curl binary, so there is nothing to install from a package index. We built and ran everything below on November 20, 2026 against the live Cursor hosts. The versions in the table are the ones we tested.
| Component | Version tested | Why you need it |
|---|---|---|
| Python | 3.12.3 | Runs the probe. The code uses 3.9-era syntax, but only 3.12.3 was tested. |
| curl | Not listed | Runs the HTTP/2 bidirectional streaming test, because the Python standard library has no HTTP/2 client. |
| Cursor editor | Current stable build from cursor.com | Provides Cursor Settings, Network, Run Diagnostics, and the cursor shell command. |
| Operating system | Not listed | Host for the probe. Resolver and proxy commands differ per OS. |
| Network access | Outbound TCP 443 | The tests open real TLS connections to Cursor hosts. |
| Time budget | 50 minutes | About 35 minutes to type and read, 15 to run and test. |
Run the probe on the same machine and in the same network as the editor. That sounds obvious, yet it is the most common source of misleading results. A probe launched inside WSL uses the Linux resolver and Linux certificate store, while the Windows editor uses the Windows ones. A probe launched on a laptop that is on the office VPN tells you nothing about the home connection where the editor failed an hour earlier.
Windows users should know that recent Windows builds ship a real curl.exe, but PowerShell 5.1 also defines curl as an alias for Invoke-WebRequest. The script calls the binary through shutil.which, which resolves to curl.exe, so the alias does not interfere. If you type curl commands by hand in PowerShell 5.1, write curl.exe explicitly.
How Cursor Reaches Its Servers, and Where It Breaks #
Cursor streams chat and agent output over HTTP/2 with bidirectional streaming by default. According to Cursor’s network configuration docs, some enterprise proxies mishandle that mode, and Zscaler is the most widely used proxy with the limitation. When bidirectional streaming fails, Cursor falls back to HTTP/1.1 with Server-Sent Events, a mode the docs say was designed to work with Zscaler and similar proxies that buffer or break HTTP/2 streams. The fallback happens transparently, so a half-working proxy often looks like slowness rather than an error.
Many corporate proxies also perform TLS inspection, which swaps Cursor’s certificate for the proxy’s own. The docs call this one of the most common deployment blockers for enterprise customers, and they recommend excluding Cursor’s domains from inspection because Cursor’s traffic is already encrypted end to end. The hosts that matter fall into a handful of groups.
| Host or pattern | What it carries | Protocol note |
|---|---|---|
| api2.cursor.sh | Most API requests | Docs say a healthy connection shows an Amazon-issued certificate |
| agent.api5.cursor.sh, agentn.api5.cursor.sh (plus us and global variants) | Agent requests and network access layer traffic | Nested subdomains, so a single-level pattern can miss them |
| api3.cursor.sh, api4.cursor.sh, regional gcpp.cursor.sh hosts | Cursor Tab requests | HTTP/2 only |
| repo42.cursor.sh | Codebase search | HTTP/2 only |
| marketplace.cursorapi.com, downloads.cursor.com, cursor-cdn.com | Updates and extension downloads | Plain HTTPS downloads |
| authenticate.cursor.sh, authenticator.cursor.sh | Authorization endpoint and sign-in UI | Authenticator is the fallback page during the sign-in transition |
| accounts.spacexsi.com, auth.grok.com and related hosts | New sign-in page and its auth hosts | Fallback retires November 30 per Cursor docs |
| cursor.com and *.cursor.com | Web dashboard, Cloud Agents web UI, code review pages | Long-lived streamed responses, sensitive to download scanning |
Anything that extends the editor adds outbound connections of its own. Every one of the MCP servers you connect talks to a separate service, so a failing MCP tool can mimic a Cursor outage while the core hosts above stay healthy. The probe in this guide covers Cursor’s own hosts, which is the right first cut. Test your MCP endpoints separately once the core path is green.
The docs also describe a manual way to test the path with curl, and the probe automates those same tests. Fetching the TLS issuer from api2.cursor.sh shows whether inspection is active, a one-second HTTP/1.1 stream test shows whether Server-Sent Events arrive line by line, and a five-message HTTP/2 stream test shows whether bidirectional streaming works. Cursor also ships a built-in check, Cursor Settings, Network, Run Diagnostics. Use both. The built-in button tests what the editor sees, and the script gives you a log you can save, diff and attach to a ticket.
Steps 1 to 3: Read the Status Page, Create the Project, Define the Hosts #
Step 1: Write down the symptom before you touch anything. Note the exact message, the time, and the surface (editor, CLI, or browser at cursor.com). Then open the status page. A message about instructions being ignored points at configuration, and the Cursor rules tutorial covers that branch. A message about waiting, timeouts, a … spinner or a failed sign-in points here. Keep the notes, because the final report has a place for them.
Step 2: Create the project folder and confirm your tools. The commands below work in macOS and Linux shells. On Windows, replace python3 with py -3.
mkdir cursor-doctor && cd cursor-doctor
python3 --version
curl --version | head -1
Run curl --version and check that the feature list includes HTTP2. If curl reports no HTTP/2 support, the bidirectional test will fall back to HTTP/1.1 and give you a false alarm. Upgrade curl first.
Step 3: Define the hosts and constants. Create cursor_doctor.py and start with the imports and the host table. Each entry carries a group label, the hostname, and a flag that says whether failure is fatal.
#!/usr/bin/env python3
"""cursor-doctor: connectivity and environment probe for Cursor."""
from __future__ import annotations
import argparse
import csv
import http.client
import json
import os
import platform
import shutil
import socket
import ssl
import subprocess
import sys
import threading
import time
from dataclasses import asdict, dataclass
from datetime import datetime, timezone
from pathlib import Path
from urllib.parse import urlsplit
HOSTS = [
("api", "api2.cursor.sh", True),
("agent", "agent.api5.cursor.sh", True),
("agent", "agentn.api5.cursor.sh", True),
("tab", "api3.cursor.sh", True),
("search", "repo42.cursor.sh", True),
("updates", "downloads.cursor.com", True),
("extensions", "marketplace.cursorapi.com", True),
("cdn", "cursor-cdn.com", True),
("auth", "authenticate.cursor.sh", True),
("auth-ui", "authenticator.cursor.sh", True),
("sign-in", "accounts.spacexsi.com", True),
("sign-in", "auth.grok.com", True),
("sign-in", "accounts.x.ai", False),
("sign-in", "accounts.spacex.ai", False),
("web", "cursor.com", True),
]
STREAM_HOST = "api2.cursor.sh"
SSE_PATH = "/aiserver.v1.HealthService/StreamSSE"
BIDI_PATH = "/aiserver.v1.HealthService/StreamBidi"
GENERATED_DIRS = ["dist", "build", ".next", "target", ".venv", "node_modules"]
Why the host list has required and optional entries
Cursor’s own pages disagree slightly about the new sign-in hosts. The sign-in help page names accounts.spacexsi.com as the new page and lists the Grok auth hosts as the minimum allowlist. The network configuration page mentions accounts.spacex.ai and accounts.x.ai. Rather than guess which page is right, the probe marks the SpaceXSI host as required and the other two as optional. A failure on an optional host downgrades to a warning, which keeps the report honest without raising a false alarm during a transition.
The list also uses the nested agent subdomains instead of api5.cursor.sh itself. Our first draft tested the bare api5 name and got a DNS failure, because the docs list the agent endpoints as agent.api5.cursor.sh, agentn.api5.cursor.sh and regional variants. A probe that fails on a name Cursor never serves is worse than no probe.
Steps 4 and 5: Probe DNS and Read the TLS Issuer #
Step 4: Add the result type and the DNS check. Every probe returns the same small record, a name, a status of ok, warn or fail, a detail string and a millisecond timer. A shared shape makes the JSON, Markdown and CSV outputs trivial later. The block below also holds three helpers used by later steps: frame builds the binary message the streaming tests send, classify_stream turns chunk arrival times into a verdict, and mask_proxy hides credentials before anything is printed.
@dataclass
class Check:
name: str
status: str # ok | warn | fail
detail: str
ms: int = 0
def frame(payload: bytes) -> bytes:
return b"\x00\x00\x00\x00" + bytes([len(payload)]) + payload
def classify_stream(offsets: list[float], window: float = 5.0) -> str:
"""streaming | buffered | silent | inconclusive, from chunk arrival offsets in seconds."""
if not offsets:
return "silent"
first, last = min(offsets), max(offsets)
if first < window * 0.5 and (last - first) >= window * 0.4:
return "streaming"
if first >= window * 0.7 and (last - first) < 1.0:
return "buffered"
return "inconclusive"
def mask_proxy(url: str) -> str:
parts = urlsplit(url)
if parts.password or parts.username:
host = parts.hostname or ""
port = f":{parts.port}" if parts.port else ""
return f"{parts.scheme}://***:***@{host}{port}"
return url
The classifier is the only clever part. A healthy stream delivers its first chunk early and keeps delivering across the test window. A buffering proxy holds everything until the stream closes, so the first chunk arrives late and the spread is tiny. Anything that fits neither pattern returns inconclusive, which surfaces as a warning instead of a hard failure. That choice keeps flaky Wi-Fi from creating phantom outages.
def check_dns(host: str) -> tuple[Check, list[str]]:
t0 = time.monotonic()
try:
infos = socket.getaddrinfo(host, 443, proto=socket.IPPROTO_TCP)
except socket.gaierror as exc:
return Check(f"dns {host}", "fail", f"no answer: {exc}", int((time.monotonic() - t0) * 1000)), []
addrs = sorted({i[4][0] for i in infos})
return Check(f"dns {host}", "ok", f"{len(addrs)} address(es)", int((time.monotonic() - t0) * 1000)), addrs
Use getaddrinfo rather than a hand-rolled DNS query. It goes through the same resolver path as most applications, so it reflects what the operating system will do, including a leftover VPN resolver. The count of addresses is a useful hint too. A CDN-fronted host usually returns several, and a single address on a name that normally returns four deserves a second look.
Step 5: Add the TLS check and read the issuer. The check opens a real connection to port 443, completes a handshake with certificate verification turned on, and reports the protocol version and the issuer. Verification matters. If a proxy replaces the certificate with one signed by a private authority your system does not trust, the handshake raises a verification error, and the probe reports it as likely TLS inspection.
def check_tls(host: str, required: bool, timeout: float) -> Check:
t0 = time.monotonic()
ctx = ssl.create_default_context()
try:
with socket.create_connection((host, 443), timeout=timeout) as raw:
with ctx.wrap_socket(raw, server_hostname=host) as tls:
cert = tls.getpeercert()
version = tls.version()
except ssl.SSLCertVerificationError as exc:
return Check(f"tls {host}", "fail", f"certificate not trusted ({exc.verify_message}), TLS inspection is likely", int((time.monotonic() - t0) * 1000))
except (OSError, ssl.SSLError) as exc:
status = "fail" if required else "warn"
return Check(f"tls {host}", status, f"connect failed: {exc}", int((time.monotonic() - t0) * 1000))
issuer = {k: v for rdn in cert["issuer"] for k, v in rdn}
label = issuer.get("organizationName") or issuer.get("commonName") or "unknown"
ms = int((time.monotonic() - t0) * 1000)
if host == STREAM_HOST and "amazon" not in label.lower():
return Check(f"tls {host}", "warn", f"{version}, issuer '{label}' (docs expect Amazon), inspection possible", ms)
return Check(f"tls {host}", "ok", f"{version}, issuer '{label}'", ms)
The docs tell you to expect an Amazon-issued certificate on api2.cursor.sh. Our first version applied that rule to every cursor.sh host and produced three warnings on a perfectly healthy network. The live hosts use different authorities: api2, the agent hosts, repo42 and the marketplace showed Amazon, while api3, downloads.cursor.com and cursor-cdn.com showed Google Trust Services, and the authentication hosts showed Let’s Encrypt. The shipped version therefore applies the issuer rule only to the host the docs name. Certificate authorities can change over time, so treat an unexpected issuer as a lead to investigate and not as proof of interception.
Steps 6 and 7: Prove Streaming Works over HTTP/1.1 and HTTP/2 #
Step 6: Replay the HTTP/1.1 streaming test. Cursor’s docs include a curl command that posts a small payload to a health endpoint on api2.cursor.sh and expects output to arrive line by line over five seconds. If everything lands at once after five seconds, a proxy is buffering the stream. The Python version below sends the same frame (four zero bytes, a length byte of 0x11, then the JSON payload {"payload":"foo"}) and timestamps each chunk with read1, which returns whatever has arrived without waiting for a full buffer.
def check_http1_stream(timeout: float = 15.0) -> Check:
t0 = time.monotonic()
body = frame(b'{"payload":"foo"}')
offsets: list[float] = []
try:
conn = http.client.HTTPSConnection(STREAM_HOST, timeout=timeout)
conn.request("POST", SSE_PATH, body, {"Content-Type": "application/connect+json"})
resp = conn.getresponse()
if resp.status == 407:
return Check("http1 stream", "fail", "407: the proxy wants credentials", int((time.monotonic() - t0) * 1000))
while True:
chunk = resp.read1(4096)
if not chunk:
break
offsets.append(time.monotonic() - t0)
conn.close()
except (OSError, http.client.HTTPException) as exc:
return Check("http1 stream", "fail", f"request failed: {exc}", int((time.monotonic() - t0) * 1000))
verdict = classify_stream(offsets)
status = {"streaming": "ok", "buffered": "fail", "silent": "warn", "inconclusive": "warn"}[verdict]
spread = f"{offsets[0]:.1f}s to {offsets[-1]:.1f}s" if offsets else "no data"
return Check("http1 stream", status, f"{verdict} ({len(offsets)} chunks, {spread})", int((time.monotonic() - t0) * 1000))
The proxy-authentication branch catches a proxy that wants credentials. Python’s http.client does not read proxy environment variables, so this branch fires only when something transparent sits in the path, such as a captive portal or an inline gateway. Keep that limitation in mind, because it also means this test can pass while the editor, which may use system proxy settings, still fails. The next step uses curl precisely because curl honors HTTPS_PROXY.
Step 7: Replay the HTTP/2 bidirectional test. The Python standard library cannot speak HTTP/2, so the probe launches curl and feeds it five messages, one per second, on standard input. Curl streams its output back, and a reader thread timestamps each chunk. If chunks arrive about once per second, bidirectional streaming works. If they all appear after five seconds, the path buffers HTTP/2 streams, which is exactly the Zscaler-style failure the docs describe.
def check_http2_bidi(count: int = 5, timeout: float = 20.0) -> Check:
curl = shutil.which("curl")
if not curl:
return Check("http2 bidi", "warn", "curl not found, skipped")
cmd = [curl, "-sS", "-N", "-o", "-", "-X", "POST", "-H", "Content-Type: application/connect+json",
"-T", "-", f"https://{STREAM_HOST}{BIDI_PATH}"]
t0 = time.monotonic()
offsets: list[float] = []
proc = subprocess.Popen(cmd, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, bufsize=0)
def reader() -> None:
while True:
data = proc.stdout.read(4096)
if not data:
return
offsets.append(time.monotonic() - t0)
thread = threading.Thread(target=reader, daemon=True)
thread.start()
try:
for i in range(1, count + 1):
proc.stdin.write(frame(f'{{"payload":"foo{i}"}}'.encode()))
proc.stdin.flush()
time.sleep(1)
proc.stdin.close()
proc.wait(timeout=timeout)
except (BrokenPipeError, subprocess.TimeoutExpired):
proc.kill()
thread.join(timeout=2)
err = proc.stderr.read().decode(errors="replace").strip()
ms = int((time.monotonic() - t0) * 1000)
if err and not offsets:
return Check("http2 bidi", "fail", f"curl: {err[:140]}", ms)
verdict = classify_stream(offsets, window=float(count))
status = {"streaming": "ok", "buffered": "fail", "silent": "warn", "inconclusive": "warn"}[verdict]
return Check("http2 bidi", status, f"{verdict} ({len(offsets)} chunks)", ms)
Two details deserve attention. The probe passes -N to disable curl’s own output buffering, because otherwise curl itself could create the delay you are trying to measure. And it kills the child process if the pipe breaks, so a dead proxy cannot leave a zombie curl running after the script exits.
Run time for these two tests is fixed. Each takes about five seconds because the server holds the stream open for that long, which is why the full probe takes roughly 12 seconds and why the --skip-h2 flag exists. Use the flag when you run the probe many times a day and only care about DNS and TLS drift.
Steps 8 and 9: Check Proxy Variables, the CLI and Your Ignore Files #
Step 8: Read proxy variables and the cursor command. Two quick checks catch an embarrassing share of problems. The first lists proxy variables set in the current shell, with credentials masked. The second runs cursor --version, which proves the shell command is installed and reports the build you are running. If the command is missing, search the command palette for the shell command install entry and run it.
def check_proxy_env() -> list[Check]:
found = []
for var in ("HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy", "ALL_PROXY", "NO_PROXY"):
if os.environ.get(var):
found.append(Check(f"env {var}", "warn", mask_proxy(os.environ[var])))
return found or [Check("env proxy", "ok", "no proxy variables in this shell")]
def check_cursor_cli() -> Check:
exe = shutil.which("cursor")
if not exe:
return Check("cursor cli", "warn", "'cursor' not on PATH (run Shell Command: Install 'cursor' command)")
try:
out = subprocess.run([exe, "--version"], capture_output=True, text=True, timeout=15).stdout.split()
except (OSError, subprocess.TimeoutExpired) as exc:
return Check("cursor cli", "warn", f"found at {exe} but --version failed: {exc}")
return Check("cursor cli", "ok", f"version {out[0] if out else 'unknown'}")
A proxy variable is a warning, not a failure, because plenty of healthy setups use one. It still earns a line in the report. A variable set in your terminal profile but absent from the editor’s environment (or the reverse) is a classic reason why curl works and Cursor does not, or why Cursor works and your scripts do not.
Step 9: Audit generated folders against your ignore files. Cursor’s performance help page says high CPU and memory use usually comes from extensions or settings, and it advises adding large generated folders such as dist/, build/ and .next/ to .cursorignore. The agent troubleshooting page adds that files listed in .cursorignore are blocked from the agent, codebase search and @ mentions, and that patterns in .gitignore can also keep files out of the agent’s reach. The check below counts files in common generated folders (stopping at 20,000) and warns when a folder with more than 500 files appears in neither ignore file. If you maintain these files by hand, the Cursor rules linter extends the idea to rules and AGENTS.md files.
def count_files(path: Path, cap: int = 20000) -> int:
total = 0
for _, _, files in os.walk(path):
total += len(files)
if total >= cap:
return cap
return total
def check_ignore(project: Path) -> list[Check]:
def lines(name: str) -> list[str]:
p = project / name
return [l.strip().strip("/") for l in p.read_text(errors="replace").splitlines()] if p.is_file() else []
cursorignore, gitignore = lines(".cursorignore"), lines(".gitignore")
results = []
for d in GENERATED_DIRS:
if not (project / d).is_dir():
continue
n = count_files(project / d)
size = f"{n}+" if n >= 20000 else str(n)
if d in cursorignore:
results.append(Check(f"ignore {d}/", "ok", f"{size} files, listed in .cursorignore"))
elif d in gitignore:
results.append(Check(f"ignore {d}/", "ok", f"{size} files, covered by .gitignore only"))
elif n > 500:
results.append(Check(f"ignore {d}/", "warn", f"{size} files and not in .cursorignore"))
return results or [Check("ignore", "ok", "no large generated folders found")]
The 500-file threshold is a judgment call, not a Cursor number. Raise it for monorepos, or lower it on a slow machine. The point of the check is to link a sluggish editor with a concrete folder name instead of leaving it as a feeling.
Steps 10 to 12: Assemble the Runner, Add Tests, and Schedule It #
Step 10: Wire everything into a runner with useful exit codes. The runner executes every check, prints one aligned line per result, and can write three artifacts: a JSON report for tooling, a Markdown table you can paste into a support ticket, and a CSV that appends one row per check per run. The exit code is 0 for all green, 1 for warnings only, and 2 if anything failed, so shell scripts and CI jobs can branch on it.
def run_all(project: Path, skip_h2: bool, timeout: float) -> list[Check]:
results: list[Check] = []
for _group, host, required in HOSTS:
dns, _addrs = check_dns(host)
if dns.status == "fail" and not required:
dns.status = "warn"
results.append(dns)
if dns.status != "fail":
results.append(check_tls(host, required, timeout))
results.append(check_http1_stream())
results.append(Check("http2 bidi", "warn", "skipped by flag") if skip_h2 else check_http2_bidi())
results.extend(check_proxy_env())
results.append(check_cursor_cli())
results.extend(check_ignore(project))
return results
def to_markdown(results: list[Check]) -> str:
rows = ["| check | status | detail | ms |", "|---|---|---|---|"]
rows += [f"| {r.name} | {r.status} | {r.detail} | {r.ms} |" for r in results]
head = f"Cursor doctor report, {datetime.now(timezone.utc):%Y-%m-%d %H:%M} UTC\n\nOS: {platform.platform()}\nPython: {platform.python_version()}\n\n"
return head + "\n".join(rows) + "\n"
def append_csv(path: Path, results: list[Check]) -> None:
new = not path.exists()
with path.open("a", newline="") as fh:
w = csv.writer(fh)
if new:
w.writerow(["ts", "name", "status", "ms"])
ts = datetime.now(timezone.utc).isoformat(timespec="seconds")
for r in results:
w.writerow([ts, r.name, r.status, r.ms])
def main() -> int:
ap = argparse.ArgumentParser(description=__doc__)
ap.add_argument("--project", type=Path, default=Path.cwd())
ap.add_argument("--json", type=Path, help="write the full report as JSON")
ap.add_argument("--markdown", type=Path, help="write a support-ticket report")
ap.add_argument("--csv", type=Path, help="append one row per check for trend tracking")
ap.add_argument("--skip-h2", action="store_true", help="skip the 5-second HTTP/2 streaming test")
ap.add_argument("--timeout", type=float, default=6.0)
args = ap.parse_args()
results = run_all(args.project, args.skip_h2, args.timeout)
width = max(len(r.name) for r in results)
for r in results:
print(f"{r.status.upper():4} {r.name:<{width}} {r.detail} ({r.ms} ms)")
if args.json:
args.json.write_text(json.dumps([asdict(r) for r in results], indent=2))
if args.markdown:
args.markdown.write_text(to_markdown(results))
if args.csv:
append_csv(args.csv, results)
fails = sum(r.status == "fail" for r in results)
warns = sum(r.status == "warn" for r in results)
print(f"\n{len(results)} checks, {fails} fail, {warns} warn")
return 2 if fails else 1 if warns else 0
if __name__ == "__main__":
sys.exit(main())
Step 11: Lock the logic down with unit tests. The network checks cannot run in a unit test without flakiness, but the decision logic can. These tests pin the streaming classifier, the frame length byte, the credential masking and the ignore-file audit. They need only the standard library, so run them with python3 -m unittest -v.
import tempfile
import unittest
from pathlib import Path
import cursor_doctor as cd
class ClassifyStream(unittest.TestCase):
def test_one_chunk_per_second_is_streaming(self):
self.assertEqual(cd.classify_stream([1.0, 2.0, 3.0, 4.0, 5.0]), "streaming")
def test_everything_at_the_end_is_buffered(self):
self.assertEqual(cd.classify_stream([5.0, 5.01, 5.02]), "buffered")
def test_no_chunks_is_silent(self):
self.assertEqual(cd.classify_stream([]), "silent")
def test_single_early_chunk_is_inconclusive(self):
self.assertEqual(cd.classify_stream([0.4]), "inconclusive")
class Helpers(unittest.TestCase):
def test_frame_length_byte_matches_payload(self):
payload = b'{"payload":"foo"}'
self.assertEqual(cd.frame(payload)[4], 0x11)
self.assertEqual(cd.frame(b'{"payload":"foo1"}')[4], 0x12)
def test_mask_proxy_hides_credentials(self):
self.assertEqual(cd.mask_proxy("http://bob:[email protected]:8080"), "http://***:***@proxy.corp:8080")
self.assertEqual(cd.mask_proxy("http://proxy.corp:8080"), "http://proxy.corp:8080")
class IgnoreCheck(unittest.TestCase):
def test_flags_large_unlisted_folder(self):
with tempfile.TemporaryDirectory() as tmp:
root = Path(tmp)
(root / "dist").mkdir()
for i in range(600):
(root / "dist" / f"f{i}.js").write_text("x")
res = cd.check_ignore(root)
self.assertEqual(res[0].status, "warn")
(root / ".cursorignore").write_text("dist/\n")
self.assertEqual(cd.check_ignore(root)[0].status, "ok")
if __name__ == "__main__":
unittest.main()
The frame test deserves a comment. Cursor’s curl examples use the length bytes 0x11 and 0x12 for the two payload shapes. A one-byte error there would send malformed frames, the server would respond differently, and you would chase a phantom proxy problem. The test catches that class of typo for free.
Step 12: Schedule the probe and keep a history. Intermittent failures are the hardest to explain, and a log turns a vague complaint into a dated observation, such as api3 handshakes crawling every afternoon at the same hour. Schedule the script every 15 minutes with the CSV flag. On Linux and macOS, a cron entry does the job. On Windows, Task Scheduler runs the same command. If you would rather run the probe from a pipeline, the Cursor CLI in GitHub Actions walkthrough shows how headless jobs are set up, and the exit codes above slot straight into a job step.
*/15 * * * * cd $HOME/cursor-doctor && python3 cursor_doctor.py --skip-h2 --csv history.csv > /dev/null 2>&1
Sample Output from a Healthy Network and Two Failures #
The first block is a trimmed run from the Ubuntu test box on November 20, 2026, with no proxy and a direct connection. All 35 checks completed in about 12 seconds, and the only warning was that the cursor command is not installed on that server.
$ python3 cursor_doctor.py --project . --json report.json --markdown support.md --csv history.csv
OK dns api2.cursor.sh 3 address(es) (2 ms)
OK tls api2.cursor.sh TLSv1.3, issuer 'Amazon' (212 ms)
OK dns agent.api5.cursor.sh 3 address(es) (1 ms)
OK tls agent.api5.cursor.sh TLSv1.3, issuer 'Amazon' (208 ms)
OK tls api3.cursor.sh TLSv1.3, issuer 'Google Trust Services' (50 ms)
OK tls authenticate.cursor.sh TLSv1.3, issuer 'Let's Encrypt' (59 ms)
OK tls accounts.spacexsi.com TLSv1.3, issuer 'Let's Encrypt' (53 ms)
...
OK http1 stream streaming (6 chunks, 0.3s to 5.3s) (5322 ms)
OK http2 bidi streaming (6 chunks) (5118 ms)
OK env proxy no proxy variables in this shell (0 ms)
WARN cursor cli 'cursor' not on PATH (run Shell Command: Install 'cursor' command) (0 ms)
OK ignore no large generated folders found (0 ms)
35 checks, 0 fail, 1 warn
$ echo $?
1
The second block shows what a broken proxy variable looks like. We pointed HTTPS_PROXY at a dead local port, with a fake username and password in the URL, and created a demo project whose dist/ folder held 800 files. Only the lines that changed are shown. Notice that the credentials never appear in the output.
$ HTTPS_PROXY=http://alice:[email protected]:9 python3 cursor_doctor.py --project demo-app
FAIL http2 bidi curl: curl: (7) Failed to connect to 127.0.0.1 port 9 after 0 ms: Couldn't connect to server (1001 ms)
WARN env HTTPS_PROXY http://***:***@127.0.0.1:9 (0 ms)
WARN ignore dist/ 800 files and not in .cursorignore (0 ms)
35 checks, 1 fail, 3 warn
Look at the contrast. The HTTP/1.1 test still reported streaming in that run, because Python ignored the variable and went direct, while curl obeyed it and failed. That split is a diagnosis in itself: when the two streaming tests disagree, a proxy setting is shaping one path and not the other. After adding dist/ to .cursorignore, the ignore line flipped to OK ignore dist/ 800 files, listed in .cursorignore and the failure count dropped back to zero once the variable was removed.
The Markdown report that --markdown writes starts with a UTC timestamp, the operating system string and the Python version, followed by a table of every check. Attach it to a support request together with the Cursor build number and, for agent failures, the request ID that the agent’s Copy Request ID menu item produces. Cursor’s agent troubleshooting page asks for that ID, your steps to reproduce, and your system details when you report a bad response on the community forum.
Turn Each Failed Check into a Fix #
The probe is only useful if every red line maps to an action. The table below pairs each failure with its most likely cause and the fix that Cursor’s documentation describes.
| Probe result | Likely cause | Fix to try first |
|---|---|---|
| dns fail on all hosts | No connectivity or a broken resolver | Check the network, then run scutil --dns on macOS or read/etc/resolv.conf on Linux |
| dns fail only after a VPN disconnect | Cursor inherited VPN resolver settings | Fully quit and restart Cursor (a window reload is not enough) |
tls certificate not trusted |
TLS inspection with a CA your system does not trust | Ask IT to exclude Cursor domains from inspection, or install the corporate CA |
| tls api2 issuer is not Amazon | Proxy replaced the certificate | Same exclusion request, with the issuer name as evidence |
http1 stream buffered |
Proxy buffers Server-Sent Events | Ask for SSE passthrough with response buffering disabled for streaming types |
http2 bidi buffered |
Proxy cannot carry HTTP/2 bidirectional streams | Set HTTP Compatibility Mode to HTTP/1.1 in Cursor Settings, Network, then restart |
| http2 bidi curl error 7 | A proxy variable points at a dead proxy | Fix or unset HTTPS_PROXY in the shell and the editor’s launch environment |
| ignore warning on a large folder | Generated files are being indexed | Add the folder to .cursorignore |
Corporate proxies and TLS inspection
Cursor’s docs recommend excluding its domains from SSL inspection and DLP, and they list the patterns: *.cursor.sh, *.cursor-cdn.com, marketplace.cursorapi.com, *.cursorvm.com and *.*.cursorvm.com, plus cursor.com and *.cursor.com. The two cursorvm.com patterns are both required for Grok Bot, because hosted computers use nested hostnames and a single-level wildcard misses them. If policy forces inspection on everything, the proxy has to support HTTP/2 bidirectional streaming (or accept the HTTP/1.1 fallback), pass Server-Sent Events through without buffering, avoid forced timeouts on long-lived connections, and disable response buffering for streaming content types.
Sign-in domains before November 30
Cursor’s sign-in help page says sign-in is moving to accounts.spacexsi.com, replacing authenticator.cursor.sh as the sign-in page, and that existing sessions stay signed in. If the new host is blocked, sign-in falls back to the old page for now. That fallback retires on November 30, so teams behind an allowlist should add the hosts this month. The docs recommend wildcards (*.spacexsi.com, *.grok.com, *.grokusercontent.com and *.grokipedia.com), and name four minimum hosts if wildcards are off the table: accounts.spacexsi.com, auth.grok.com, auth.grokusercontent.com and auth.grokipedia.com. The probe already tests the first two, so a red line there is an early warning, not an incident.
Cloud Agents stuck on
One failure never shows up in the desktop app. Agents sit on a … screen at cursor.com/agents while the same agents open normally in the editor. Cursor’s docs trace this to secure web gateways, including Cloudflare Gateway with the WARP client, Zscaler and Netskope, which treat the long-lived compressed stream from cursor.com as a file download and hold the body until it closes. The page can take ten minutes or more to render. In browser developer tools, the telltale sign is a StreamConversation request under /api/connect-proxy/ with no status code and nothing transferred. The fix is to exclude cursor.com and *.cursor.com from TLS inspection and file scanning, on roaming and off-network profiles as well as office ones. The probe’s tls cursor.com line will usually look normal in this case, so use it to confirm DNS and handshake health and rely on the browser test for the stream itself.
Common Pitfalls When You Run a Cursor Status Check #
- Trusting a green status page. It reports Cursor’s side only. A green page with a red local probe means your path is the problem, and no amount of refreshing will change that.
- Probing from the wrong place. WSL, a container, or an SSH session each has its own resolver and certificate store. Run the probe in the same environment as the editor, then run it again from a second network (a phone hotspot is the quickest) to isolate the path.
- Reading a Python pass as proof. The standard library ignores proxy environment variables, and the editor may use system proxy settings. When the HTTP/1.1 and HTTP/2 results disagree, believe the curl result for proxy questions and the built-in Run Diagnostics button for what the editor sees.
- Flagging every unfamiliar certificate issuer. Only api2.cursor.sh is documented as Amazon-issued. Other hosts legitimately use other authorities, and a rule that warns on all of them buries the one real signal.
- Re the window after a VPN change. The docs are explicit that a full restart clears inherited environment variables, while a reload does not.
- Allowlisting by apex only. Nested names such as
agent.api5.cursor.shand*.*.cursorvm.comneed their own patterns, and a few S3 and blob hosts used for skills sync and Remote SSH server downloads are not matched by the main wildcards at all. - Pasting secrets into a support ticket. Proxy URLs often carry a username and password. The probe masks them, and you should keep that habit when you copy raw environment dumps into chat.
- Ignoring the date. Teams that bookmarked
authenticator.cursor.shwill hit trouble after November 30 if the allowlist never gained the new sign-in hosts.
A related trap is blaming Cursor’s instruction files for a network fault. Persistent instruction formats such as the open AGENTS.md convention shape what an agent does, but they cannot make a blocked stream flow. Rule out the network first, and only then tune instructions.
Troubleshooting: 10 Symptoms and Their Fixes #
- Agent Execution Timed Out, or Timeout waiting for EverythingProvider. Cursor’s docs say the extension host did not finish starting within 60 seconds. Collect logs before changing anything: runDeveloper: Export Logs… from the command palette, select Main, Window and Extension Host, and check the Extension Host output panel. An empty panel is a strong signal. On managed machines, endpoint security software is one possible cause.
- The probe is all green but the editor still fails. The editor may use system proxy settings that the script does not see. Open Cursor Settings, Network, click Run Diagnostics, and compare. Then test with extensions off using
cursor --disable-extensions. - Cloud Agents hang on … in the browser only. Suspect a secure web gateway that scans downloads, as described above. Turn the gateway client off or open cursor.com/agents from another network to confirm.
- http1 stream reports buffered. A proxy is holding Server-Sent Events. Ask for passthrough without buffering, or exclude Cursor domains from the proxy entirely.
- http2 bidi reports buffered or fails while HTTP/1.1 passes. Open Cursor Settings, Network, set HTTP Compatibility Mode to HTTP/1.1, and restart Cursor. Tab and codebase search use HTTP/2 only on their hosts, so ask IT about those two as well.
- DNS errors after leaving a VPN. Quit Cursor completely and relaunch it. If it persists, confirm the system resolver reverted:
scutil --dnson macOS,/etc/resolv.confon Linux. - A suspicious activity message. The docs say this appears when a request is blocked as a security measure, and VPNs can trigger it. Turn off the VPN, start a new chat, wait a few minutes, or sign in with a different method such as Google or GitHub.
- AI features die over Remote SSH. AI requests leave your local machine, not the remote host, so check the local connection first. Then look at memory and CPU on the remote server, and add
ServerAliveInterval 60andServerAliveCountMax 3to the SSH config if the session drops. If the remote host cannot reach the download hosts, setremote.SSH.localServerDownloadtoalways. - Sign-in loops or is blocked. Add the sign-in hosts to the allowlist, retry from
accounts.spacexsi.com, and update old bookmarks before November 30. - The agent returns poor results, not errors. That is rarely a network problem. Cursor’s docs suggest starting new chats between tasks, attaching files with @, and using Plan mode first for tasks that touch many files, which theCursor Plan Mode guide covers in detail.
Advanced Tips for Teams and Power Users #
Hand IT a machine-readable list. The HOSTS table doubles as an allowlist request. Export it as JSON, attach the doc patterns above, and ask for exclusions in one ticket instead of a drip of single-host requests.
Track handshake time, not just pass or fail. The CSV records milliseconds per check. Chart tls api3.cursor.sh over a week and a slow window usually lines up with a backup job, a VPN reconnect or a bad Wi-Fi channel. Slowness without errors is the pattern behind most reports of Cursor taking longer than expected.
Compare two networks in one command. Run the probe on the office network, then on a phone hotspot, and diff the two Markdown reports. If the hotspot is green and the office is red, the path is the problem, and you now hold the evidence.
Alert on exit code 2. Wrap the script in a shell function that posts to a chat webhook when the exit code is 2, and stays quiet on 0 and 1. Cursor hooks can run scripts around agent events too, so a hook could call the probe before a long agent run and refuse to start one on a broken path. Treat that as an experiment and read the hooks docs for the events available.
Keep a fallback agent ready. When the status page shows a real incident, the best response is a second tool that does not depend on the same backend, such as the setup in the Claude Code tutorial or the Codex CLI guide. Switching takes minutes if the CLI is already installed and authenticated.
Validate before a rollout. Run the probe from a pilot laptop before you push Cursor to a department. A red line during a pilot costs an afternoon. The same red line after a rollout costs a hundred tickets.
Respect the data boundary. The probe sends only the documented health-test payload (the literal text foo) to a health endpoint on api2.cursor.sh, plus ordinary DNS lookups and TLS handshakes. It never reads your code, your Cursor settings or your account tokens, and the report contains only hostnames, timings and issuer names.
The Complete Project at a Glance #
The finished project is two files and three generated artifacts. Paste the code blocks from Steps 3 to 10 into cursor_doctor.py in order, save the Step 11 tests beside it, and run the commands below.
cursor-doctor/
cursor_doctor.py # the probe (about 270 lines)
test_cursor_doctor.py # 7 unit tests, standard library only
report.json # generated by --json
support.md # generated by --markdown
history.csv # appended by --csv
python3 -m unittest -v
python3 cursor_doctor.py --project /path/to/your/repo --json report.json --markdown support.md --csv history.csv
echo "exit code: $?"
Exit code 0 means every check passed, 1 means warnings only, and 2 means at least one failure. When a run ends in 2, work down the table in the fixes section, change one thing, and run the probe again. Changing two things at once is how teams end up with a fix nobody can explain. For more editor and agent workflows, the software and developer tools section collects the rest of the Cursor guides.
FAQ: Cursor Status, Outages and Connection Errors #
How do I check Cursor status?
Open the Check system status link at the bottom of a Cursor help page, which leads to Cursor’s status page (we reached it at status.cursor.com). That tells you whether Cursor has a known incident. Then run the probe in this guide to test your own path, because a green status page does not cover your network.
Why is Cursor taking longer than expected?
The message appears when a response stalls. Typical causes are a proxy that buffers streaming responses, TLS inspection that adds delay, a stale VPN resolver, or an active outage. The probe separates these in about 12 seconds, and Cursor Settings, Network, Run Diagnostics gives a second opinion from inside the editor.
Is Cursor down or is it my network?
Check the status page first. If it shows an incident, wait. If it is green and the probe shows a failure on DNS, TLS or streaming, the fault is on your path. If both are green, export the logs and test with cursor --disable-extensions, since the remaining suspects are extensions and endpoint security software.
How do I switch Cursor to HTTP/1.1?
Go to Cursor Settings, Network, set HTTP Compatibility Mode to HTTP/1.1, and restart Cursor. Cursor’s docs recommend this when a corporate proxy such as Zscaler blocks HTTP/2 streaming. Cursor also falls back to HTTP/1.1 Server-Sent Events on its own when bidirectional streaming fails.
Which domains must I allowlist?
Cursor’s docs list *.cursor.sh, *.cursor-cdn.com, *.cursorapi.com, *.cursorvm.com, *.*.cursorvm.com, cursor.com and *.cursor.com, plus the sign-in hosts accounts.spacexsi.com, auth.grok.com, auth.grokusercontent.com and auth.grokipedia.com. A few S3 and blob storage hosts used for skills sync and Remote SSH downloads are not covered by the patterns, so add them if your firewall is strict.
Does the probe send my code anywhere?
No. It sends a fixed health-test payload to a health endpoint, performs DNS lookups and TLS handshakes, and reads local metadata such as proxy variables, the cursor --version output and file counts in generated folders. The reports contain no source code and no tokens, and proxy credentials are masked.
Will sign-in break on November 30?
According to Cursor’s sign-in help page, the fallback to the old sign-in page retires on November 30, after which sign-in requires accounts.spacexsi.com. Existing sessions stay signed in and nobody gets logged out, but a user who signs in fresh from a network that blocks the new host will be stuck. Add the hosts now and confirm with the probe.