> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plasma.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues, diagnostics, and resolution procedures

This guide outlines common problems affecting non-validator nodes, with practical diagnostics and resolution steps. Rapid troubleshooting is critical for maintaining RPC availability and reliable access to stablecoin transaction data.

<Note>
  Most issues stem from system resource limits, network connectivity with consensus endpoints, or misconfiguration. Always begin with basic health checks before investigating Plasma-specific edge cases.
</Note>

## Synchronisation Issues

<AccordionGroup>
  <Accordion title="Node Lags Behind">
    If your node falls behind the network head:

    * **Check system load**: CPU, memory, and I/O must be sufficient for Plasma's high-frequency block production.
    * **Verify consensus endpoint latency**: High latency impacts block ingestion speed.
    * **Monitor database performance**: Slow queries or lock contention can bottleneck sync.

    **Diagnostics:** Check `block_height` vs network head, state application time per block, and latency to each consensus endpoint.
  </Accordion>

  <Accordion title="Sync Stalls Completely">
    If syncing halts:

    * **Check disk space**: Full disks halt database writes.
    * **Verify endpoint connectivity**: Ensure DNS resolution, firewall rules, and routing are not blocking consensus traffic.
    * **Check container resource limits**: Insufficient memory or CPU can crash sync processes.

    **Plasma-specific checks:** Verify endpoint reachability, valid JWT tokens / allowlist status, and non-validator node version compatibility.
  </Accordion>

  <Accordion title="Poor Peer Connectivity">
    Limited or unstable connections to consensus endpoints reduce data freshness for RPC consumers.

    **Check:** IP restrictions or routing policies, endpoint connection count and uptime, and failover behavior across multiple endpoints.

    **Key metrics:** Active connections, disconnect rate, and block arrival lag.
  </Accordion>
</AccordionGroup>

## Network Connectivity

### Port and Firewall Access

Ensure required ports are open for both:

* **Consensus communication**
* **RPC serving to applications**

Common blockers include corporate firewalls, cloud security groups, or misconfigured iptables rules.

**Verify:**

* Port reachability from outside and inside container
* Allowed outbound traffic for consensus sync

### DNS Failures

Unresolved consensus domains break sync.

* Confirm DNS resolution for all Plasma service domains
* Monitor resolver latency and reliability
* Add fallback resolvers as needed

### Proxy and NAT Issues

Complex networking environments (VPNs, proxies, NATs) may interfere with:

* Consensus sync
* RPC inbound access

**Validate:**

* Proxy authentication rules
* NAT port forwarding for inbound RPC
* Routing paths to Plasma infrastructure

## Configuration Errors

<AccordionGroup>
  <Accordion title="Invalid Non-Validator Config">
    Startup errors are often caused by incorrect or missing consensus endpoints, malformed URLs or JWT tokens, or deprecated flags.

    **Check logs for:** Configuration parse errors, chain ID mismatches, and unknown flags or options.
  </Accordion>

  <Accordion title="Docker Issues">
    Misconfigured containers can prevent normal operation.

    **Validate:** Volume mounts for database persistence, network access inside container, resource limits (CPU, memory), and image version compatibility.
  </Accordion>

  <Accordion title="Environment Variable Conflicts">
    Conflicting or misordered env vars may override intended settings.

    **Verify:** Consensus endpoint URLs and tokens, network and chain ID, and feature flags (e.g. custom gas support). Document environment variable usage to avoid drift between deployments.
  </Accordion>
</AccordionGroup>

## Resource Limits

### Disk Space

Monitor disk usage growth due to:

* Blockchain data
* Logs and temporary files

**Best practices:**

* Implement log rotation
* Schedule cleanup jobs
* Monitor usage alerts

### File Descriptor

Low ulimits can break:

* Consensus connections
* RPC sessions

Increase file descriptor limits via `ulimit`, systemd, or container runtime configs.

## Diagnostics

### Log Analysis

Use logs to trace:

* Sync progress
* RPC errors
* Consensus connectivity
* Resource-related crashes

**Best practices:**

* **Consensus synchronisation logs**: Track connectivity and sync progress with Plasma.
* **Transaction processing logs**: Monitor transaction handling and errors.
* **RPC request logs**: Analyse payment application request patterns and performance.
* **Resource utilisation logs**: Identify bottlenecks affecting payment processing.

### Performance Profiling

Profile non-validator workloads to identify bottlenecks in:

* RPC performance
* DB query latency
* Consensus state application

**Focus areas:**

* Balance check throughput
* Transfer confirmation latency
* Resource usage under load

Maintain baselines and track changes across upgrades or config changes.

Systematic troubleshooting and observability are essential to reliable non-validator node operation. Proper diagnostics, logging, and configuration hygiene ensure stable performance and uptime for RPC services supporting stablecoin infrastructure.