> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thornode.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Troubleshooting
> Diagnose ThorNode authentication, capacity, transport, streaming, UDP, and payment symptoms.
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
Note the product, network, location, access identifier, timestamp, and
timezone. Do not record the credential or complete URL.
Confirm that the pass or rental is active, then review **Overview → Network
status**, **Usage**, and **Limits** for the selected access.
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.
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](#authentication-fails) for `401`, `403`, or `Unauthenticated`; [method or route errors](#method-or-route-is-not-found) for a missing method or route; [live-limit failures](#requests-or-subscriptions-are-rate-limited) for `429` or rejected concurrent work; and [connection failures](#connection-dns-or-tls-fails) 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](/reference/security#credential-scope-and-placement). | 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](/reference/security#rotate-or-revoke-a-credential) 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](/reference/plans-and-limits#understand-the-monthly-and-live-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:
```bash theme={null}
dig +short
```
Do not paste a tokenized URL into shared terminal output. When a location itself changed, follow [move a workload to another location](/reference/locations#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](/products/yellowstone-grpc) and [Pulse production guidance](/products/pulse/production) 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:
```bash theme={null}
export UDP_PORT=''
sudo tcpdump -ni any "udp port ${UDP_PORT}"
```
Stop the capture after collecting enough evidence. Continue with the [Raw Shred Stream receiver checks](/products/raw-shred-stream#troubleshooting) or [Replay troubleshooting](/products/shredreplay#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](/legal/refunds) separately.
## Contact support safely
Contact [ThorNode support](mailto:support@thornode.io) or use the official [Thor Labs Discord](https://discord.gg/thorlabs). 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.
## Next steps
* [Verify dynamic access and capacity](/reference/plans-and-limits)
* [Correct target and credential location scope](/reference/locations)
* [Rotate or revoke an exposed credential](/reference/security#rotate-or-revoke-a-credential)