Plugin Troubleshooting

Common issues and solutions for Pixlpay game server integrations.

Connection Issues

Authentication Failed (HTTP 401/403)

Symptoms:

• "Authentication failed" in logs
• "Unauthorized" error messages
• Commands not being received

Solutions:

1. Verify your secrets are correct

   • Check Store Secret and Server Secret in your config
   • Copy secrets fresh from the dashboard (don't retype)
   • Ensure no extra spaces or characters

2. Check store status

   • Log in to your Pixlpay dashboard
   • Verify your store is approved and active
   • Ensure the game server is registered

3. Regenerate secrets

   • Go to Settings > Game Servers
   • Click on your server
   • Generate new Server Secret
   • Update your plugin config

4. Check for typos

   • Store Secret and Server Secret are different
   • Ensure you're using the right one in each field

RCON Connection Failed

Symptoms:

• "Connection refused" errors
• "RCON connection failed" messages
• Agent unable to start

Solutions:

1. Verify RCON is enabled on your game server

   • Check your game server configuration
   • Ensure RCON port is set
   • Confirm RCON password is configured

2. Check port and host

   • Use 127.0.0.1 if running on the same machine
   • Verify the port matches your server config
   • Test with a standalone RCON client

3. Check firewall

   # Windows
   netstat -an | findstr <port>
   
   # Linux
   ss -tlnp | grep <port>

4. Verify password

   • No extra spaces in password
   • Match exactly what's in server config
   • Some special characters may need escaping

API Connection Issues

Symptoms:

• "Connection timeout" errors
• "Network unreachable" messages
• Intermittent failures

Solutions:

1. Check internet connectivity

   # Test API endpoint
   curl https://api.pixlpay.net/health

2. Check firewall for outbound HTTPS

   • Port 443 must be allowed for outbound connections
   • Some hosting providers block outbound by default

3. Check for proxy settings

   • If behind a proxy, configure accordingly
   • Some corporate networks block API calls

4. Check DNS resolution

   nslookup api.pixlpay.net

Command Execution Issues

Commands Not Executing

Symptoms:

• Poll succeeds but no commands run
• Player doesn't receive items
• No errors in logs

Solutions:

1. Check delivery queue

   • Use /pixlpay queue (Rust/Valheim)
   • Use queue command in interactive mode (Go Agent)
   • May be waiting for player to come online

2. Verify player identification

   • Check customer linked their Steam account
   • Verify Steam ID format is correct
   • Test with a known working Steam ID

3. Enable debug mode

   • Set debug mode to true in config
   • Check detailed logs for issues
   • Look for "skipped" or "ignored" messages

4. Test command manually

   • Run the exact command in game console
   • Verify syntax is correct for your game
   • Check for typos in item IDs

Command Execution Failed

Symptoms:

• Errors in logs about command failure
• "Execution error" messages
• Order shows as failed

Solutions:

1. Test command syntax

   • Run command manually in game console
   • Verify item IDs are correct (case-sensitive)
   • Check placeholder formatting

2. Check player status

   • Player may need to be online
   • Player inventory may be full
   • Player may not have required permissions

3. Check game-specific requirements

   • Some commands need admin privileges
   • Some items can't be given while dead
   • World state may affect availability

Player Not Found

Symptoms:

• "Player not found" errors
• Command executes but nothing happens
• Works for some players, not others

Solutions:

1. Verify player identifier

   • Check Steam ID format (17-digit SteamID64)
   • Username must match exactly (case-sensitive)
   • Player must be on the server

2. Check "Wait for Online" setting

   • If enabled, commands queue until player joins
   • Check queue for pending commands
   • Verify player has connected since purchase

3. Test with known working player

   • Use your own account for testing
   • Verify the identifier format works

Configuration Issues

Plugin Not Loading

Symptoms:

• Plugin doesn't appear in list
• No logs from plugin
• Commands don't work

Solutions:

1. Check installation location

   • Rust: oxide/plugins/PixlPay.cs
   • Valheim: BepInEx/plugins/PixlPay.dll
   • Verify file is in correct directory

2. Check dependencies

   • Valheim requires BepInEx + Server devcommands
   • Rust requires Oxide/uMod
   • Verify all dependencies installed

3. Check for errors during load

   • Rust: Check oxide/logs/
   • Valheim: Check BepInEx/LogOutput.log
   • Look for error messages at startup

4. Reload the plugin

   • Rust: oxide.reload PixlPay
   • Valheim: Restart server

Config Not Loading

Symptoms:

• Default values being used
• Changes not taking effect
• "Config not found" messages

Solutions:

1. Verify config file location

   • Rust: oxide/config/PixlPay.json
   • Valheim: BepInEx/config/com.pixlpay.valheim.cfg
   • Go Agent: pixlpay-config.json in working directory

2. Check JSON/config syntax

   • Use a JSON validator
   • Look for missing commas, quotes
   • Ensure proper encoding (UTF-8)

3. Check file permissions

   • Plugin must be able to read the file
   • Check ownership and permissions

Wrong API Endpoint

Symptoms:

• Dev mode enabled accidentally
• Wrong URL in status
• Connection to wrong server

Solutions:

1. Check dev mode setting

   • Set Dev Mode / dev_mode to false
   • Remove or blank Dev API URL
   • Reload/restart plugin

2. Verify platform_url

   • Should be https://api.pixlpay.net
   • No trailing slash
   • Check for typos

Logging and Debugging

Enable Debug Mode

Rust Plugin:

/pixlpay debug

Or set in config:

{
  "Debug Mode": true
}

Valheim Plugin: Edit com.pixlpay.valheim.cfg:

DebugMode = true

Go Agent: Set in pixlpay-config.json:

{
  "debug_mode": true
}

Log File Locations

Integration	Log Location
Rust	oxide/logs/PixlPay/
Valheim	BepInEx/LogOutput.log
Go Agent	logs/ directory

What to Include in Support Requests

When contacting support, include:

1. Plugin version - From status command
2. Game and platform - e.g., "Rust with Oxide 2.0"
3. Error messages - Exact text from logs
4. Steps to reproduce - What you did before the error
5. Configuration - Redact secrets, include settings
6. Recent changes - What changed before the issue

Common Error Messages

Error	Meaning	Solution
401 Unauthorized	Invalid credentials	Check Store/Server secrets
403 Forbidden	Server not registered	Add server in dashboard
404 Not Found	Endpoint not found	Check API URL
429 Too Many Requests	Rate limited	Reduce poll frequency
500 Server Error	API issue	Wait and retry, contact support
Connection refused	RCON not reachable	Check RCON config/firewall
Command not recognized	Invalid command	Verify command syntax

Discord Bot Issues

"Bot is not in guild"

Symptoms:

• Error message: "Bot is not in guild"
• Role assignment fails

Solutions:

1. Invite the bot to your server

   • Go to Discord Developer Portal > OAuth2 > URL Generator
   • Select scopes: bot and applications.commands
   • Select permissions: Manage Roles
   • Use the generated URL to invite the bot

2. Verify guild ID

   • Right-click your Discord server
   • Click "Copy Server ID" (enable Developer Mode if hidden)

"Member not found in guild"

Symptoms:

• Error: "Member not found in guild"
• Role assignment fails for specific customer

Solutions:

1. Customer must join your Discord server before receiving roles
2. Have customer run /claim in your Discord server after joining
3. Consider requiring Discord at checkout to prevent this

Bot Can't Assign Role

Symptoms:

• Role assignment fails
• "Missing permissions" errors

Solutions:

1. Check role hierarchy

   • Go to Discord Server Settings > Roles
   • Drag the bot's role above all roles it needs to assign
   • Save changes

2. Check bot permissions

   • Re-invite the bot with Manage Roles permission
   • Or manually add "Manage Roles" in Server Settings > Roles

Commands Not Appearing

Symptoms:

• /claim, /check, /help commands don't show up
• "Unknown command" errors

Solutions:

1. Wait for propagation

   • Slash commands can take up to 1 hour to appear globally

2. Re-invite with correct scopes

   • Go to Discord Developer Portal > OAuth2 > URL Generator
   • Select both bot and applications.commands scopes
   • Re-authorize the bot

3. Re-register commands

   • Go to Settings > Integrations > Discord in your Pixlpay dashboard
   • Click "Re-register Commands"

"Interaction failed" Error

Symptoms:

• Discord shows "This interaction failed"
• Commands don't respond

Solutions:

1. Verify Interactions Endpoint URL

   • In Discord Developer Portal > General Information
   • URL should be: https://api.pixlpay.net/webhook/discord/interactions/{your-store-slug}
   • No trailing slashes

2. Check bot is enabled

   • Go to Settings > Integrations > Discord in Pixlpay
   • Ensure bot is enabled

3. Re-save credentials

   • Re-enter Application ID, Public Key, and Bot Token
   • Click Save

Customer Not Receiving Role

Symptoms:

• Customer runs /claim but gets "No pending deliveries"
• Order shows as delivered but customer doesn't have role

Solutions:

1. Check Discord link

   • Customer must have linked their Discord account on your store
   • They can do this in their account settings

2. Check customer is in server

   • Customer must be a member of your Discord server

3. Check order delivery status

   • Go to Orders in your dashboard
   • Check the delivery status for the order

4. Check role configuration

   • Ensure the product has Discord role delivery enabled
   • Verify the correct role is selected

Getting Help

If you've tried these solutions and still have issues:

1. Check integration-specific guides

   • Discord Integration
   • Project Zomboid
   • Rust
   • Valheim

2. Join our Discord

   • Discord Community
   • Real-time help from staff and community

3. Contact Support

   • Submit a ticket
   • Include log files and configuration