temporal-cloud

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 - SDK setup for connecting to Cloud
HA namespace connectivity - multi-region endpoint and DNS setup
Dev Success troubleshooting guide - 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

Symptom: tcld login not working
│
├─ Can `tcld account get` run?
│  ├─ Yes → Login is valid; continue with account verification
│  └─ No → Run `tcld login`
│
├─ Token refresh failed?
│  └─ tcld logout && tcld login
│
├─ Wrong organization/account?
│  ├─ tcld account get
│  └─ Verify the expected namespace appears in `tcld namespace list`
│
└─ "unauthorized" or auth errors?
   └─ tcld logout && tcld login

Connection Failures

Docs: 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.
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:

Auth method: API key vs mTLS
Address / HostPort: should be Namespace Endpoint (<ns>.<acct>.tmprl.cloud:7233) for most cases
Namespace: full Cloud namespace format (<namespace>.<account-id>)
TLS config: empty tls.Config{} is normal for API key auth; client cert/key required for mTLS
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 - 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

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 covers all SDK connection options

Temporal Cloud Skill

Help users diagnose and resolve Temporal Cloud connectivity, authentication, and configuration issues using tcld and temporal CLI.

Core Philosophy

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 - SDK setup for connecting to Cloud
HA namespace connectivity - multi-region endpoint and DNS setup
Dev Success troubleshooting guide - 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

Symptom: tcld login not working
│
├─ Can `tcld account get` run?
│  ├─ Yes → Login is valid; continue with account verification
│  └─ No → Run `tcld login`
│
├─ Token refresh failed?
│  └─ tcld logout && tcld login
│
├─ Wrong organization/account?
│  ├─ tcld account get
│  └─ Verify the expected namespace appears in `tcld namespace list`
│
└─ "unauthorized" or auth errors?
   └─ tcld logout && tcld login

Connection Failures

Docs: 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.
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.

SDK Snippet Review

When the user pastes SDK config, validate the config itself before suggesting lower-level networking checks.

Review in this order:

Auth method: API key vs mTLS
Address / HostPort: should be Namespace Endpoint (<ns>.<acct>.tmprl.cloud:7233) for most cases
Namespace: full Cloud namespace format (<namespace>.<account-id>)
TLS config: empty tls.Config{} is normal for API key auth; client cert/key required for mTLS
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 - 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

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 covers all SDK connection options

Other names for this repo

Temporal Cloud Skill

Core Philosophy

Issue Classification

The Process

Step 1: Identify the Category

Step 2: Gather Context

Step 3: Apply Decision Tree

Step 4: Provide Fix

Decision Trees

tcld Login Issues

Connection Failures

Ambiguous Runtime Errors

SDK Snippet Review

Certificate Errors

Namespace Issues

Worker Issues

HA Namespace Connectivity

Private Connectivity Issues

Rate Limiting

Common Scenarios

Common Pitfalls

Tips

Other names for this repo

Temporal Cloud Skill

Core Philosophy

Issue Classification

The Process

Step 1: Identify the Category

Step 2: Gather Context

Step 3: Apply Decision Tree

Step 4: Provide Fix

Decision Trees

tcld Login Issues

Connection Failures

Ambiguous Runtime Errors

SDK Snippet Review

Certificate Errors

Namespace Issues

Worker Issues

HA Namespace Connectivity

Private Connectivity Issues

Rate Limiting

Common Scenarios

Common Pitfalls

Tips