Troubleshooting Guide

Support

Common issues, solutions, and diagnostic procedures for VoxelAI. Find quick fixes and detailed troubleshooting steps.

Quick Diagnostics

Start with the basic diagnostics section to identify common issues. Most problems can be resolved with simple configuration changes.

Common Issues

Plugin Won't Load

Symptoms:

Plugin not appearing in /plugins list, no config files generated

Solutions:

1. Check Java version (requires Java 21+)

2. Verify server version (Paper 1.21+)

3. Check console for error messages

4. Ensure plugin file isn't corrupted

Configuration Errors

Symptoms:

YAML parsing errors, invalid configuration warnings

Solutions:

1. Validate YAML syntax online

2. Check indentation (use spaces, not tabs)

3. Verify quotes around string values

4. Reset to default config if needed

Diagnostic Commands

System Diagnostics

/voxelai health

Check overall system health

/voxelai stats

View system statistics

/voxelai debug on

Enable debug logging

Testing Commands

/voxelai test "test message"

Test violation detection

/ai help

Test AI assistant

/voxelai version

Check plugin version

Log Analysis

Error Patterns

API_ERROR

Check API key and connectivity

RATE_LIMIT

Enable hybrid model selection

QUEUE_OVERFLOW

Increase processing speed

Performance Indicators

High Response Time

API or network issues

Memory Warning

Reduce queue size

Processing Delay

Optimize batch settings

Configuration Issues

YAML_ERROR

Fix configuration syntax

INVALID_VALUE

Check parameter ranges

MISSING_KEY

Add required configuration

Step-by-Step Troubleshooting

General Troubleshooting Process

Follow these steps for any VoxelAI issue

Check System Status

Run /voxelai health and /voxelai stats

Review Logs

Check error logs for recent issues and patterns

Verify Configuration

Ensure all settings are correct and API key is valid

Test Components

Test AI assistant and violation detection separately

Apply Solutions

Implement fixes based on identified issues

Monitor Results

Verify fixes work and monitor for recurring issues

Getting Help

Before Asking for Help

• Check this troubleshooting guide

• Review recent log files

• Try basic diagnostic commands

• Note exact error messages

• Document steps to reproduce

Information to Include

• VoxelAI version

• Server version and type

• Java version

• Error messages and logs

• Configuration files

• Steps to reproduce issue

Emergency Procedures

System Failure

1. Disable VoxelAI temporarily

2. Check server logs

3. Restore from backup

4. Contact support

False Positive Storm

1. Increase confidence thresholds

2. Add temporary exemptions

3. Review recent changes

4. Monitor closely

API Quota Exceeded

1. Enable emergency queue

2. Reduce processing frequency

3. Wait for quota reset

4. Consider API upgrade