Monitor Troubleshooting

Solutions to common issues when integrating and running ByteHide Monitor on Android.

Token Issues

"Invalid token" or "Token not found"

Cause: The ByteHide project token is missing or incorrect.

Solution:

1. Verify your token at cloud.bytehide.com under your project Settings
2. Ensure the BYTEHIDE_TOKEN environment variable is set correctly
3. Check that the token matches your Monitor project (not a Shield or Secrets token)
4. If using JSON configuration, verify the projectToken field

"Token expired" or "Unauthorized"

Cause: The project token has been revoked or the project was deleted.

Solution:

1. Log in to cloud.bytehide.com
2. Navigate to your Monitor project
3. Generate a new token if needed
4. Update the token in your environment or configuration file

False Positives

Debugger detection triggering in development

Cause: The debugger detection module detects your IDE's debugger during development.

Solution:

• Use the NONE or LOG action for debugger detection during development
• Use cloud configuration to easily toggle actions between development and production
• Use a separate Monitor project for development with relaxed settings

Emulator detection in CI/CD

Cause: CI/CD environments may be detected as emulators due to virtualized hardware.

Solution:

• Use LOG action for emulator detection in CI/CD pipelines
• Disable emulator detection in CI/CD environments using environment-specific configuration
• Use cloud configuration with separate projects for CI/CD vs production

VM detection on cloud servers

Cause: Cloud servers (AWS, Azure, GCP) run on hypervisors that are detected as virtual machines.

Solution:

• For cloud-hosted applications, use LOG or NONE action for VM detection
• VM detection is primarily useful for desktop and mobile applications
• Consider disabling VM detection for server-side deployments

SQL Injection false positives on legitimate queries

Cause: Some legitimate user input may contain patterns that resemble SQL injection (e.g., search queries with quotes or keywords like OR, AND).

Solution:

• Review the incident in the Incidences dashboard to check the confidence score. Low-confidence detections are more likely to be false positives
• Use the LOG action instead of BLOCK while evaluating the pattern
• Configure endpoint-specific overrides to relax protections on specific routes that handle complex user input

Requests blocked unexpectedly (HTTP 403)

Cause: A web protection module is blocking legitimate requests.

Solution:

1. Enable debug logging temporarily to see which module triggered the block and why
2. Check the reference code in the 403 response to find the corresponding incident in the dashboard
3. Adjust the protection configuration or action for the specific module

Configuration Issues

Protections not activating

Cause: Configuration is not being loaded properly.

Solution:

1. Enable debug logging to see Monitor's startup sequence
2. Verify the configuration priority: Cloud Dashboard overrides JSON, which overrides code
3. Check that protections have "enabled": true in your configuration
4. Verify the JSON file is in the project root with a recognized filename

Cloud configuration not updating

Cause: The application cannot reach the ByteHide API.

Solution:

1. Verify network connectivity to api.bytehide.com
2. Check firewall rules and proxy settings
3. Verify the token has not expired
4. Monitor will continue with its last known configuration if the cloud is unreachable

Performance

High CPU usage

Cause: Protection check intervals are too frequent.

Solution:

• Increase the intervalMs for protection modules (e.g., from 30000 to 60000 or 120000)
• Disable protection modules that are not relevant to your deployment environment
• Use targeted protections instead of EnableAllProtections

Slow application startup

Cause: Monitor initialization is blocking the main thread.

Solution:

• For cloud configuration, Monitor initialization includes an API call. Ensure good network connectivity
• Use JSON or embedded configuration for faster startup in latency-sensitive environments
• Consider async initialization where supported

Getting Help

If you cannot resolve your issue:

1. Enable debug logging and collect the log output
2. Note your Monitor SDK version, Android version, and framework version
3. Check the Incidences dashboard for related incidents and their details
4. Contact ByteHide support at cloud.bytehide.com with the information above

Next Steps