Common Issues

Plugin Won't Enable

Symptoms: ZyveraWeb disables itself on startup with a console error.

Causes and solutions:

Error Message	Solution
Invalid port: X. Must be between 1 and 65535	Fix port in config.yml
host cannot be empty	Set host to a valid IP
Missing rate-limit.X configuration	Ensure both rate-limit sections (placeholder, players) exist
rate-limit.X must have valid 'requests' and 'per' fields	Check that requests > 0 and per has a valid duration

Web Server Won't Start

Symptoms: /zyveraweb server start fails or the server crashes on startup.

Possible causes:

Cause	Solution
Port already in use	Stop the conflicting service or change port
Invalid host binding	Use 0.0.0.0 to bind all interfaces
SSL certificate not found	Check ssl/ folder and site SSL config paths
Permission denied (port < 1024)	Use a port above 1024, or run as root
GraalJS context failed	Ensure you're using a GraalVM-compatible JDK

PlaceholderAPI Returns 401

Symptoms: /api/placeholder returns HTTP 401 Unauthorized.

Solutions:

• Ensure a token is set in the plugin configuration
• Include the Authorization: Bearer <token> header in requests
• Verify PlaceholderAPI is installed and loaded

Node.js Sites Not Working

Symptoms: Node.js sites show an error page or "No script engine available".

Solutions:

• Verify you're using a GraalVM JDK (java -version should show GraalVM)
• Check that server.js exports a handle function
• Ensure server.js syntax is valid (errors are caught and returned in the response)
• Run /zyveraweb node list to verify the project is detected

npm Installation Fails

Symptoms: npm packages are not installed or installation messages show failures.

Solutions:

• Check internet connectivity to registry.npmjs.org
• Verify package.json has valid JSON syntax
• Check the console for specific error messages about individual packages
• Ensure the server has outbound HTTPS access

404 Errors

Symptoms: All requests return 404.

Solutions:

• Verify virtual host configuration matches the requested domain
• Check that the folder paths are correct
• For static sites, ensure files exist in the configured folder
• For Node.js sites, verify both public/ and server.js are set up correctly

Rate Limiting Too Aggressive

Symptoms: Legitimate requests getting 429 responses.

Solutions:

• Increase rate-limit.placeholder.requests or rate-limit.players.requests in config.yml
• Restart the web server with /zyveraweb server restart for changes to take effect

Cannot Connect from Browser

Symptoms: Browser shows "Connection refused" or timeout.

Solutions:

• Check that the web server is running (/zyveraweb status)
• Verify the port is open in your firewall
• Ensure host is not set to 127.0.0.1 (use 0.0.0.0 for external access)
• Check that your hosting provider allows the port

SSL Certificate Issues

Symptoms: Browser shows certificate warnings or ERR_CERT_* errors.

Solutions:

• For Let's Encrypt: Ensure the domain resolves to your server IP
• For self-signed: This is expected; use a real certificate for production
• Check that fullchain.pem contains the full chain (not just the leaf certificate)
• Verify the private key matches the certificate