Diagnosing Server Lag#

This guide provides a systematic approach to identifying and resolving server lag issues.

Types of Lag#

Before troubleshooting, identify which type of lag you're experiencing:

Connection Issues (One Player)#

If only one player experiences lag:

• Check their internet connection
• Try using Cloudflare 1.1.1.1 for improved DNS
• Verify they're connecting to the nearest server region

Client FPS Issues#

If a player has low FPS:

• Increase allocated RAM in their launcher
• Install client-side optimization mods:
  • Sodium (Fabric)
  • Entity Culling
  • Starlight

Diagnosing Server Lag#

Step 1: Install Spark#

Spark is a performance profiling tool. It comes pre-installed on:

• QualityNode Fabric/Forge modded servers
• Paper-based plugin servers

If not installed, add it from Modrinth.

Step 2: Check TPS#

Run this command in your console:

spark tps

Interpreting results:

A consistent 20.0 TPS means the server isn't overloaded. Look for connection or client issues instead.

Step 3: Generate a Profile#

If TPS drops below 20, create a performance report:

spark profiler start

Wait 1-2 minutes while the server is lagging, then:

spark profiler stop

This generates a shareable link to analyze.

Step 4: Analyze the Profile#

The profiler shows what's consuming server resources. Click through the tree to identify:

• Which mods/plugins use the most tick time
• Entity processing overhead
• World generation costs

Common Causes and Solutions#

Too Many Entities#

Symptoms: Lag in specific areas with many mobs/items

Solutions:

• Kill excess entities: /kill @e[type=item]
• Reduce simulation-distance in server.properties
• Add mob stacking plugins (Paper servers)
• Clear item entities regularly

Chunk Generation Lag#

Symptoms: Lag when players explore new areas

Solutions:

• Pre-generate your world with Chunky
• Set a world border to limit exploration
• Reduce view-distance

Heavy Datapacks#

Symptoms: Constant low TPS, visible in spark profile

Solutions:

• Remove or disable resource-intensive datapacks
• Use mods instead for complex modifications

Problematic Mods/Plugins#

Symptoms: Specific mod/plugin appears high in spark profile

Solutions:

• Check mod documentation for known issues
• Update to the latest version
• Remove or replace the problematic mod
• Contact the modpack maintainers for pre-made packs

Redstone Machines#

Symptoms: Lag when near large redstone contraptions

Solutions:

• Use Alternate Current (Fabric)
• Optimize or reduce redstone complexity
• Disable redstone when not in use

Server Settings to Adjust#

In server.properties:

view-distance=8
simulation-distance=4

For Paper servers, also check config/paper-world-defaults.yml for additional optimization options.

Getting Help#

If you can't resolve the issue:

1. Generate a spark profile
2. Note your server software and version
3. List installed mods/plugins
4. Contact QualityNode support with this information

See Also#

• Pre-generate with Chunky
• Pre-installed Fabric Mods
• Automatic Restarts