Fix Temporal Cloud connection, auth, and config problems. Use when users hit login failures, can't connect to Cloud, get x509/TLS errors, have namespace or endpoint mismatches, paste broken SDK connection snippets, are confused about which endpoint to use, see "no pollers" or RESOURCE_EXHAUSTED, str

Temporal Cloud Skill Help users diagnose and resolve Temporal Cloud connectivity, authentication, and configuration issues using tcld and temporal CLI. Core Philosophy Cloud issues are frustrating because they sit at the intersection of configuration, networking, authentication, and Temporal specific code. Most problems fall into predictable patterns. This skill provides systematic diagnosis to quickly identify root causes and prescribe fixes. References: See references/cloud troubleshooting reference.md for full CLI command reference and error codes See references/common scenarios.md for step by step setup walkthroughs [Environment configuration docs](https://docs.temporal.io/develop/environment configuration) SDK setup for connecting to Cloud [HA namespace connectivity](https://docs.temporal.io/cloud/high availability/ha connectivity) multi region endpoint and DNS setup [Dev Success troubleshooting guide](https://github.com/temporalio/dev success/blob/main/troubleshooting connection issues to temporal cloud.md) companion connection troubleshooting guide Out of scope: Worker performance tuning, scaling, metrics interpretation, SDK specific config, deployment patterns. Those topics are covered by separate worker focused skills. Issue Classification Category Key Symptoms First Check tcld Login login failed, token refresh failed, wrong account tcld account get Connection/Auth can't connect, access denied, handshake failures Endpoint format + DNS + port connectivity Ambiguous Runtime Errors context deadline exceeded , workflow is busy Identify the operation and layer first mTLS/Certs x509 errors, unknown authority, expired openssl x509 enddate Namespace namespace not found, SNI mismatch Namespace name format HA / Failover Failover not working, wrong region, DNS stale DNS CNAME resolution Worker Tasks not picked up, stale connections temporal task queue describe Private Connectivity PrivateLink/PSC errors VPC endpoint status Rate Limiting RESOURCE EXHAUSTED APS limits The Process Step 1: Identify the Category Ask the user: What's the exact error message? (copy paste if possible) What are you trying to do? (tcld command, starting workers, running workflows) What changed recently? (new certs, new namespace, new region) Step 2: Gather Context For SDK/client snippet reviews: Which auth method are you using: API key or mTLS? Which SDK and version are you using? What exact HostPort / address are you using? What exact Namespace are you using? Is this SDK code, temporal CLI, or tcld ? For tcld issues: Can you run tcld account get ? Multiple Temporal accounts? For connection issues: What's your exact address / HostPort ? Using mTLS or API keys? Which SDK and version are you using? Any firewall/proxy between you and Cloud? For ambiguous runtime errors: Where exactly do you see the error: workflow start, signal/update, polling, querying, logs? Is this happening before work starts, while polling, or while workflow code is already running? Are pollers present on the relevant task queue? Did this start after a traffic spike, deploy, or config change? For certificate issues: When were certs generated? What CA was used? Is CA uploaded to namespace? For worker issues: Are workers running? How many? What does temporal task queue describe show? Any errors in worker logs? Step 3: Apply Decision Tree Use the appropriate decision tree based on category (see below). Step 4: Provide Fix Give specific commands to resolve the issue, with verification steps. Always include a confidence score for the proposed diagnosis or fix: Confidence: 9 10/10 when the symptom, operation, and confirming signals line up cleanly Confidence: 6 8/10 when the evidence is good but one plausible alternative remains Confidence: 1 5/10 when the issue is still ambiguous and the "fix" is really the next discriminating check If the problem is ambiguous, say so explicitly and keep the recommendation scoped to the next check rather than presenting a speculative root cause as settled. Decision Trees tcld Login Issues Connection Failures Docs: [Environment configuration](https://docs.temporal.io/develop/environment configuration) SDK connection options Endpoint check before network debugging: Use case Recommended endpoint Notes Workers & clients (all auth) <namespace .<account .tmprl.cloud:7233 Namespace Endpoint works for both mTLS and API key auth. Recommended for all namespaces. Multi region HA (advanced) <region .<cloud provider .api.temporal.io:7233 Regional Endpoint only needed for advanced HA routing. See [namespace access docs](https://docs.temporal.io/cloud/namespaces access namespaces). tcld / Cloud Ops API saas api.tmprl.cloud Control plane Exception: Namespaces using Flexible Auth (pre release) cannot use Namespace Endpoints yet. Ambiguous Runtime Errors Do not assume these are pure connectivity failures. Classify them by operation first. Error text Common interpretations First discriminator context deadline exceeded wrong endpoint, network timeout, oversized payload, blocked execution path, client side timeout Where in the flow does it occur? workflow is busy / RESOURCE EXHAUSTED: Workflow is busy operation level contention, workload pressure, confusing user facing error semantics Which operation returned it? no pollers no connected workers, workers present but misconfigured, stale/misleading metrics Does temporal task queue describe show pollers? Use this decision sequence: If the operation and surrounding signals still do not make the error interpretable, label it as ambiguous and gather more context before prescribing a fix. When responding, attach a confidence score from 1 10 to the proposed diagnosis or next step. Ambiguous cases should carry a low confidence score and a narrow next check rather than a broad claimed fix. SDK Snippet Review When the user pastes SDK config, validate the config itself before suggesting lower level networking checks. Review in this order: 1. Auth method: API key vs mTLS 2. Address / HostPort : should be Namespace Endpoint ( <ns .<acct .tmprl.cloud:7233 ) for most cases 3. Namespace: full Cloud namespace format ( <namespace .<account id ) 4. TLS config: empty tls.Config{} is normal for API key auth; client cert/key required for mTLS 5. Environment config: prefer TEMPORAL ADDRESS , TEMPORAL NAMESPACE , TEMPORAL API KEY , TEMPORAL TLS CLIENT CERT PATH , TEMPORAL TLS CLIENT KEY PATH Common snippet diagnoses: Using regional endpoint ( .api.temporal.io ) when Namespace Endpoint would work → simplify to <ns .<acct .tmprl.cloud:7233 Empty HostPort + Cloud namespace/auth → missing explicit Cloud endpoint API key without TLS enabled by the SDK/runtime → check SDK specific Cloud guidance Old endpoint format (stale docs/examples) → update to current Namespace Endpoint If the snippet is wrong, fix that first. Do not lead with DNS/TLS debugging until the endpoint and namespace are plausible. Certificate Errors Namespace Issues Worker Issues This skill diagnoses Cloud connectivity issues for workers. Worker performance tuning, scaling, and deployment patterns are out of scope. Docs: [Environment configuration](https://docs.temporal.io/develop/environment configuration) SDK connection setup Scope clarification: Issue Type In Scope? tcld login, certs, namespace, private connectivity Yes Worker scaling, metrics, tuning, deployment No "Workers not picking up tasks" Yes diagnose, hand off if not a Cloud issue HA Namespace Connectivity Docs: [HA namespace connectivity](https://docs.temporal.io/cloud/high availability/ha connectivity) HA (multi region) namespaces use a hierarchical DNS structure: Namespace endpoint: <ns .<acct .tmprl.cloud (CNAME to active region) Regional endpoint: <region .region.tmprl.cloud During failover, CNAME switches regions (15s TTL, ~30s convergence) Worker placement for HA: Option A: Run workers in both regions continuously Option B: Single region + Transit Gateway/VPC Peering for failover access Private Connectivity Issues Rate Limiting Common Scenarios See references/common scenarios.md for step by step walkthroughs: API key connectivity setup New namespace setup (mTLS) Certificate rotation Switching from mTLS to API keys Common Pitfalls Pitfall Why It Happens Fix Wrong namespace format Using short name instead of name.account id Use full namespace from tcld namespace list Self signed certs Trying to use self signed without CA Generate CA first, sign certs with it, upload CA Regional endpoint when unnecessary Using .api.temporal.io when Namespace Endpoint works Switch to <namespace .<account .tmprl.cloud:7233 Old endpoint docs Following stale examples from before Namespace Endpoints were universal Use Namespace Endpoint: <ns .<acct .tmprl.cloud:7233 Expired certs Not monitoring expiry Set up alerts, rotate before expiry tcld wrong account Logged into different org Use tcld account get , then verify the namespace in tcld namespace list Stale tcld login Cached auth state is no longer valid tcld logout && tcld login DNS caching K8s pods caching old DNS Restart pods after endpoint changes Missing port Firewall blocks 7233 Ensure egress allowed on port 7233 Tips Always get the exact error message Copy paste, don't paraphrase Check the simple things first DNS, port connectivity, cert expiry Use Namespace Endpoint by default <ns .<acct .tmprl.cloud:7233 works for both mTLS and API key auth Use openssl for cert issues It gives clearer error messages than SDKs tcld account get is your friend Shows the current account context Namespace names are case sensitive Match exactly API keys are easier than mTLS Consider for simpler setups Point users to env config docs [Environment configuration](https://docs.temporal.io/develop/environment configuration) covers all SDK connection options

temporal-cloud