Troubleshooting

Start with the symptom, check one condition at a time, and retry only transient failures. The sections below show what to inspect, change, or send to support.

Run the quick triage

Record the scope

Note the product, network, location, access identifier, timestamp, and timezone. Do not record the credential or complete URL.

Check current state

Confirm that the pass or rental is active, then review Overview → Network status, Usage, and Limits for the selected access.

Refresh the configuration

Compare the application’s target and credential scope with the values currently shown together in the dashboard. Redact both before logging or sharing the comparison.

Reduce to one operation

Test one low-impact request, connection, or subscription from the production runtime network. Disable unbounded retries while diagnosing it.

HTTP and RPC responses

Start with authentication failures for 401, 403, or Unauthenticated; method or route errors for a missing method or route; live-limit failures for 429 or rejected concurrent work; and connection failures for 5xx or timeouts.

Authentication fails

Symptom	Verify	Expected result	Action	Retry?
HTTP `401` or `403`, or gRPC `Unauthenticated`	Access is active; product and location are enabled; target and credential came from the same location; credential placement matches Security.	One minimal operation authenticates with the current dashboard values.	Correct the access, location, or credential placement. Regenerate only when the value is stale or exposed.	No, until configuration or access changes.
A valid ThorEdge token is rejected after an IP restriction	Determine the runtime’s public egress IPv4 after NAT, gateway, VPN, or proxy and check for multiple egress paths.	The address observed by ThorNode matches the one saved for the token.	Route through the intended stable gateway or update the restriction, then test from the same runtime.	No, until the address matches.
RPC works but WebSocket fails	The client uses the complete `wss://` URL for the same location; outbound proxy and firewall policy allow WebSockets.	RPC and WebSocket authenticate from the same allowed network.	Replace the URL with the current dashboard value and correct proxy or firewall policy.	No for a configuration block; yes with backoff after a transient disconnect.
A token works in one location but not another	Compare the target’s location with the token’s location.	A location-bound token is used only with its matching target.	Create or retrieve the destination location credential and change target and credential together.	No, until both values match.

Do not retry authorization errors in a tight loop. Rotation does not fix an inactive access, unavailable product, wrong location, or incorrect IP restriction. Follow the safe rotation procedure when rotation is actually required.

Method or route is not found

Refresh the supported-method list or Private TX catalog for the selected access and location, then copy the complete URL again. Retry only after the method or route appears.

Requests or subscriptions are rate limited

Symptom	Verify	Expected result	Action	Retry?
HTTP `429`	Compare recent traffic, concurrency, and retry volume with Usage and Limits for the exact access.	Sustained traffic remains below the live per-second or concurrent limit.	Reduce concurrency, stop duplicate work, reuse connections, and apply exponential backoff with jitter.	Yes, after delay and load reduction.
A WebSocket subscription is rejected	Check Limits → RPC endpoint → WebSocket subscriptions and inspect duplicate subscriptions.	The new subscription fits within the displayed capacity.	Reuse connections, close unused subscriptions, or request more capacity before retrying.	Yes, after capacity is available.
A Yellowstone subscription is rejected	Check Limits → gRPC Yellowstone → Concurrent streams and Accounts across filters; inspect duplicate streams.	The new subscription fits within the displayed capacity and uses supported narrow filters.	Close unused streams, narrow filters, or request more capacity before retrying.	Yes, after capacity is available.
A Raw Shred Stream registration is rejected	Check whether the product is enabled and how many registrations are active for the access and location.	The new receiver fits within the live registration allowance.	Remove an unused registration or contact support about capacity.	Yes, after capacity is available.

Creating another client, credential, or reconnect loop does not increase capacity. See Plans and limits for monthly and live limit behavior.

Connection, DNS, or TLS fails

Symptom	Verify	Expected result	Action	Retry?
DNS lookup fails or the host is unreachable	The public hostname exactly matches the dashboard; the runtime’s DNS, VPN, proxy, firewall, and service mesh permit the route.	The hostname resolves and the documented port is reachable from the application runtime.	Refresh the target and correct local network policy. Do not substitute a resolved IP or use an internal address.	No, until configuration or network policy changes.
TLS or certificate validation fails	System clock, trusted certificate authorities, hostname, and the client’s trust configuration.	A certificate-validating client accepts the copied target.	Restore the dashboard hostname and trust configuration. Add a private CA explicitly when required; do not disable production verification.	No, until trust is correct.
HTTP `5xx`, timeout, or unexpected disconnect	Overview → Network status, one minimal operation, and a comparison from another runtime or location.	The test distinguishes a service incident from one client’s network or load problem.	Preserve the time and a redacted request identifier if returned; retry a small, bounded number of times with backoff.	Yes, when transient.

Test DNS without exposing a credential:

dig +short <public-hostname-copied-from-dashboard>

Do not paste a tokenized URL into shared terminal output. When a location itself changed, follow move a workload to another location.

Yellowstone or Pulse streaming fails

Symptom	Verify	Expected result	Action	Retry?
Yellowstone authentication fails	Target and token belong to the same location; metadata key is exactly `x-token`; token is not in the URL.	A minimal `Subscribe` stream authenticates.	Correct the metadata and location pairing.	No, until corrected.
Yellowstone cannot connect or rejects a subscription	Plaintext HTTP/2 (`h2c`) mode, `x-token` metadata, filter shape, and Limits → gRPC Yellowstone.	One narrow filter connects and returns an update.	Compare the request with the current Dragon’s Mouth proto, reduce filters, and close unused streams.	No for request errors; yes with backoff after transient disconnects.
Pulse handshake or authentication fails	Target and token came from the same location; outbound UDP works; certificate validation, ALPN `pulse`, and wire version `2` are enabled.	The first control message returns an `ok: true` acknowledgement.	Correct the UDP path, target, trust configuration, or token, then reconnect.	No, until corrected.
Pulse closes with code `3`	Current concurrent streams and account-filter use for the selected access.	The subscription fits the capacity currently available.	Reduce active work and retry with bounded exponential backoff and jitter.	Yes, with backoff.
Pulse closes with code `5`	The selected access includes Pulse and the request contains an account filter when one is required.	The subscription shape is available for the selected access.	Change the access or filter before reconnecting.	No, not unchanged.
A streaming consumer falls behind or shows a gap after reconnect	Receive-path work, queue bounds, reconnect frequency, and consumer lag.	The client processes through bounded queues and detects discontinuity after a reconnect.	Move expensive work downstream, bound memory and concurrency, back off reconnects, and reconcile state when correctness requires it.	Yes, after stabilizing the consumer; never open parallel reconnect storms.

See Yellowstone gRPC and Pulse production guidance for their connection settings and error handling.

Raw Shred Stream or Replay sends no UDP data

Symptom	Verify	Expected result	Action	Retry?
No UDP packets arrive	The dashboard target is the intended public numeric IPv4 and UDP port; the process listens on that port; firewall, security-group, ACL, NAT, and forwarding rules allow it.	A short capture on the receiver shows datagrams on the registered port.	Correct the target or network path. A host behind carrier-grade NAT needs a reachable server or explicit forwarding.	No, until the path is reachable.
Replay slot range is rejected	Refresh the rolling minimum and maximum slots displayed by the dashboard.	Both requested slots remain inside the current window.	Choose a current range.	Yes, with corrected values.
Replay reports another job is active	Check the selected access for a queued or running replay.	Only one replay job is queued or running per access.	Wait for completion or cancel the existing job before starting another.	Yes, after the job clears.
Packets arrive but the receiver drops data	Socket-drop metrics, receive-path work, queue bounds, and Replay pacing.	The receiver drains UDP promptly and tolerates loss, duplication, and reordering.	Reduce receive-path work; use bounded downstream queues; for Replay, switch from maximum speed to original pacing.	Retrying alone does not fix receiver overload.

Run a brief capture on the receiver to separate a network failure from an application failure:

export UDP_PORT='<registered-port>'
sudo tcpdump -ni any "udp port ${UDP_PORT}"

Stop the capture after collecting enough evidence. Continue with the Raw Shred Stream receiver checks or Replay troubleshooting for product-specific behavior.

Payment is signed but access is not updated

Do not pay again. Keep the transaction signature and return to the same payment page. Use Check now, Retry Failed Passes, or another verification action shown there. If no action is available or the payment remains unresolved, contact support with the signature and approximate time. Payment recovery reconciles an existing transaction with dashboard access. It is not a refund request. Contact support about a refund separately.

Contact support safely

Contact ThorNode support or use the official Thor Labs Discord. Include:

Product, network, and location
Access identifier and tier, without private wallet material
Approximate timestamp and timezone
HTTP or gRPC status and a redacted error message
Client name and version
What changed immediately before the symptom
Transaction signature and dashboard recovery reference for payment recovery, when relevant

Never include endpoint tokens, Bifrost credentials, replay keys, complete credential-bearing URLs, wallet private keys, or seed phrases. For a suspected credential exposure, rotate first and then report the product, location, and exposure window.

Get started

Dashboard

Operate

Run the quick triage

HTTP and RPC responses

Authentication fails

Method or route is not found

Requests or subscriptions are rate limited

Connection, DNS, or TLS fails

Yellowstone or Pulse streaming fails

Raw Shred Stream or Replay sends no UDP data

Payment is signed but access is not updated

Contact support safely

Next steps

​Run the quick triage

​HTTP and RPC responses

​Authentication fails

​Method or route is not found

​Requests or subscriptions are rate limited

​Connection, DNS, or TLS fails

​Yellowstone or Pulse streaming fails

​Raw Shred Stream or Replay sends no UDP data

​Payment is signed but access is not updated

​Contact support safely

​Next steps

Run the quick triage

HTTP and RPC responses

Authentication fails

Method or route is not found

Requests or subscriptions are rate limited

Connection, DNS, or TLS fails

Yellowstone or Pulse streaming fails

Raw Shred Stream or Replay sends no UDP data

Payment is signed but access is not updated

Contact support safely

Next steps