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.com/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.com

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.com
   • 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 Agent Issues

Agent Not Starting

Symptoms:

• Missing required environment variables error
• Cannot find module errors
• Agent crashes immediately

Solutions:

1. Check environment variables

   • Verify .env file exists and is configured
   • PIXLPAY_API_KEY and DISCORD_BOT_TOKEN are required
   • Run cat .env to verify values are set

2. Install dependencies

   npm install

3. Check Node.js version

   node --version  # Must be 18.0.0 or higher

"Bot is not in guild"

Symptoms:

• Error message: "Bot is not in guild"
• Operations fail for specific guild ID

Solutions:

1. Invite the bot to your server

   • Go to Discord Developer Portal > OAuth2 > URL Generator
   • Select scopes: bot
   • 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)
   • Compare with the guild_id in error messages

"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. Consider requiring Discord at checkout to prevent this
3. The operation will retry automatically when they join

"Bot does not have Manage Roles permission"

Solutions:

1. Re-invite the bot with correct permissions:

   • Go to Discord Developer Portal > OAuth2 > URL Generator
   • Select permissions: Manage Roles

2. Or manually add permission:

   • Server Settings > Roles
   • Find the bot's role
   • Enable "Manage Roles" permission

"Bot's highest role is not above the target role"

Solutions:

1. Go to Discord Server Settings > Roles
2. Find the bot's role (e.g., "My Store Bot")
3. Drag it above all roles you want the bot to assign
4. Save changes

"Could not reach Pixlpay API"

Symptoms:

• Network errors in agent logs
• Timeouts when polling

Solutions:

1. Check internet connectivity

   curl https://yourstore.pixlpay.net/api/v1/discord-agent/pending

2. Verify API URL

   • Check PIXLPAY_API_URL in your .env file
   • Should be your store's full URL

3. Verify API key

   • Ensure PIXLPAY_API_KEY is correct
   • Check the token has discord:agent scope

"Token does not have discord:agent scope"

Solutions:

1. Create a new API token in your dashboard
2. Go to Settings > API Tokens
3. Create token with discord:agent scope selected
4. Update PIXLPAY_API_KEY in your .env file
5. Restart the agent

Agent Polling But No Operations

Symptoms:

• Agent runs without errors
• No role assignments happening
• Dashboard shows pending deliveries

Solutions:

1. Verify Discord is configured in Pixlpay

   • Go to Settings > Integrations > Discord
   • Ensure Client ID and Client Secret are set

2. Check guild ID matches

   • Guild ID in Pixlpay must match your Discord server

3. Check product configuration

   • Product must have Discord role delivery enabled
   • Role must be selected for the product

Discord Agent Logs

View logs with PM2:

pm2 logs pixlpay-discord-agent

View logs with Docker:

docker logs <container_id>

View logs with systemd:

journalctl -u pixlpay-discord-agent -f

Getting Help

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

1. Check integration-specific guides

   • Discord Agent
   • 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