Monitor Troubleshooting

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

Build Issues

Plugin not found

Plugin [id: 'com.bytehide.monitor', version: '1.0.1'] was not found

Plugin [id: 'com.bytehide.monitor', version: '1.0.1'] was not found

Solution: Add mavenCentral() to pluginManagement.repositories in settings.gradle.kts:

pluginManagement {
    repositories {
        mavenCentral()
        gradlePluginPortal()
        google()
    }
}

pluginManagement {
    repositories {
        mavenCentral()
        gradlePluginPortal()
        google()
    }
}

No API token configured

WARNING: No API token configured (offline mode)

WARNING: No API token configured (offline mode)

Solution: Set the token in one of these locations (checked in order):

1. monitor { projectToken = "bh_xxx" } in build.gradle.kts
2. BYTEHIDE_API_TOKEN environment variable
3. bytehide.api.token=bh_xxx in local.properties

Could not detect package name

ERROR: Could not detect package name

ERROR: Could not detect package name

Solution: Set it explicitly in the plugin DSL:

monitor {
    packageName = "com.example.myapp"
}

monitor {
    packageName = "com.example.myapp"
}

Failed to obtain application security signature

BUILD FAILED: Could not obtain application security signature

BUILD FAILED: Could not obtain application security signature

Causes: invalid or expired API token, no internet access during build, or ByteHide server temporarily unavailable.

Solution: Verify your token at app.bytehide.com and check your network connection.

Token Issues

"Invalid token" or "Token not found"

Cause: The ByteHide project token is missing or incorrect.

Solution:

1. Verify your token at app.bytehide.com under your project Settings
2. Ensure the BYTEHIDE_API_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 app.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

No logs in Logcat

Check these in order:

1. Filter Logcat by tag ByteHideMonitor
2. Verify android.permission.INTERNET is in the manifest
3. Do a clean build: ./gradlew clean assembleDebug
4. Check that the plugin ran during build (look for "Configuring ByteHide Monitor..." in build output)

Monitor doesn't seem to initialize

If you see no [I001_INIT_START] log at all:

1. Clean the build: ./gradlew clean
2. Invalidate caches in Android Studio: File > Invalidate Caches > Invalidate and Restart
3. Rebuild from scratch

"Registering device..." hangs

If logs stop at [I010_API_CONNECTED] Registering device..., check internet connectivity on the device/emulator, verify the API token is valid, and check if a proxy or VPN is intercepting connections.

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. Use Monitor.configure() (async) on Android to avoid ANR errors

Desktop / Server Issues

Missing dependency

ClassNotFoundException: com.bytehide.monitor.Monitor

ClassNotFoundException: com.bytehide.monitor.Monitor

Solution: Add the dependency to your build:

dependencies {
    implementation("com.bytehide:monitor-core:1.0.1")
}

dependencies {
    implementation("com.bytehide:monitor-core:1.0.1")
}

Token not found

Ensure you're passing the token before calling any protection methods:

Monitor.configure(config -> {
    config.useToken(System.getenv("BYTEHIDE_MONITOR_TOKEN"));
    config.enableAllProtections(ActionType.LOG, 60000);
});

Monitor.configure(config -> {
    config.useToken(System.getenv("BYTEHIDE_MONITOR_TOKEN"));
    config.enableAllProtections(ActionType.LOG, 60000);
});

How do I check if Monitor is running?

boolean running = Monitor.isInitialized();
String sessionId = Monitor.getSessionId();  // null if not connected

boolean running = Monitor.isInitialized();
String sessionId = Monitor.getSessionId();  // null if not connected

How do I run offline (without backend)?

export BYTEHIDE_MONITOR_OFFLINE=true

export BYTEHIDE_MONITOR_OFFLINE=true

Detections run locally, threats are logged to console/file, but no data is sent to the dashboard.

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