Documentation/Troubleshooting

Troubleshooting

Solutions to common issues with M00N Report reporters, API connections, and MCP integration.

Quick Links

Reporter Issues
API Connection Issues
MCP / AI Integration Issues
Self-Hosted Issues

Reporter Issues

"No results appearing in dashboard"

Verify your API key is set correctly as an environment variable
Check the console output for error messages from the reporter
Ensure the serverUrl is correct (include https://)
Verify network connectivity to M00N Report

"Authentication failed" from reporter

Check your project API key starts with m00n_
Verify the key hasn't been regenerated in Project Settings
Ensure you're using a project API key, not an MCP key

"Connection timeout" during test runs

Check network connectivity to M00N Report servers
If behind a proxy, configure proxy settings for your test runner
Try increasing timeout settings in reporter configuration

API Connection Issues

Testing API connectivity

Use curl to verify you can reach the M00N Report API:

# For SaaS
curl https://m00nreport.com/api/health

# For self-hosted
curl https://your-m00n-instance.com/api/health

# Expected response:
# {"status":"ok","version":"1.0.0"}

"CORS error" in browser console

This usually indicates you're calling the API from frontend code
API keys should only be used in backend/CI environments
The frontend uses JWT authentication, not API keys

"Rate limit exceeded"

Wait for the retry-after period indicated in the response
Implement request batching in automated tooling
Contact support if you have legitimate high-volume needs

MCP / AI Integration Issues

"Cannot connect to M00N Report API"

Verify M00N_API_URL is correct and doesn't include trailing slashes
Test connectivity: curl https://your-url/api/health
Check if VPN is required for internal self-hosted instances
Verify firewall allows outbound connections to the M00N Report port

"Authentication failed: Invalid or revoked MCP key"

Verify the key starts with m00n_mcp_
Check if the key has been revoked in Settings → MCP Keys
Ensure you're using an MCP key, not a project API key
Verify the key was copied correctly (no extra spaces or characters)

"SSL certificate error" / "UNABLE_TO_VERIFY_LEAF_SIGNATURE"

For self-signed certificates: Add M00N_INSECURE_SSL=true to config
For corporate CA: Add the CA certificate to your system's trust store
Verify the SSL certificate hasn't expired

"No tools available"

Check that your user account has access to at least one project
Verify the MCP key was created for a user with project permissions
Admins see all projects; users/managers only see assigned projects

"Tool not found" or empty responses

Restart Claude Desktop or Cursor after updating configuration
Check the MCP server is listed in your AI assistant's tools panel
Enable debug mode with M00N_DEBUG=true to see detailed logs

Enabling MCP Debug Logging

Add M00N_DEBUG=true to see detailed connection logs:

{
  "mcpServers": {
    "m00n": {
      "command": "npx",
      "args": ["-y", "@m00nsolutions/mcp-server"],
      "env": {
        "M00N_API_URL": "https://m00nreport.com",
        "M00N_API_KEY": "m00n_mcp_your_key_here",
        "M00N_DEBUG": "true"
      }
    }
  }
}

For more MCP troubleshooting, see the Self-Hosted MCP Setup guide.

Self-Hosted Issues

"Database connection failed"

Verify PostgreSQL is running and accessible
Check DATABASE_URL environment variable is correct
Ensure the database user has proper permissions

"Redis connection refused"

Verify Redis is running on the expected port (default 6379)
Check REDIS_URL environment variable
Real-time features require Redis; some features may be degraded without it

"License validation failed"

Verify your subscription token is correctly configured
Check network connectivity to the license server (m00nreport.com)
Self-hosted instances need periodic license validation (graceful degradation if offline)

Container health checks failing

Check container logs: docker logs m00n-api
Verify environment variables are set correctly
Ensure sufficient memory is allocated (minimum 512MB recommended)

Getting Help

If you're still experiencing issues:

Documentation: Check the relevant section for detailed guides
Discord Community: Report bugs, request features or ask the community
Email Support: support@m00nreport.com for account or billing issues

When reporting issues, please include:

M00N Report version (visible in Settings → About)
Reporter/MCP server version
Error messages and logs
Steps to reproduce the issue

← Self-Hosted