> ## 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.

## Synchronisation Issues

> [accordion] 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] 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] 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.

## 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

> [accordion] 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] 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] 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.

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.