Troubleshooting

Common issues and solutions to help you resolve problems quickly.

Extension Not Loaded Errors

If you see errors about the MemoryShield extension not being loaded:

Symptoms

• Error: "Extension memoryshield not loaded"
• Error: "This encoded file cannot be run"
• Application fails to start

Solutions

1. Verify Extension Installation:

   php -m | grep memoryshield

   If not found, reinstall the extension following the installation guide.
2. Check php.ini:

   php --ini

   Ensure extension=memoryshield.so (or .dll on Windows) is present.
3. Verify Extension Path:

   php -i | grep extension_dir

   Ensure the extension file exists in this directory.
4. Check File Permissions:

   ls -la $(php-config --extension-dir)/memoryshield.so

   Ensure the file is readable by PHP.
5. Restart Web Server:

   # Apache
   sudo systemctl restart apache2
   
   # Nginx + PHP-FPM
   sudo systemctl restart php8.1-fpm

License Activation Problems

Issues with license activation and validation:

Problem: License Key Not Found

Possible Causes:

• License key was entered incorrectly
• License has been revoked or deleted
• License belongs to a different product

Solution:

1. Verify the license key in your customer portal
2. Check that the license status is "active"
3. Ensure you're using the correct product
4. Try copying the key again (watch for extra spaces)

Problem: Device Hash Mismatch

Symptoms: License activation fails with device hash error

Solution:

• If device binding is enabled, ensure you're activating on the correct device
• Check that system information hasn't changed significantly
• Contact support if device binding needs to be reset

Problem: License Expired

Solution:

1. Check license expiry date in customer portal
2. Renew the license if needed
3. Use the refresh endpoint to update the LAT token

Problem: Seat Limit Reached

Symptoms: "Maximum seats exceeded" error

Solution:

1. Check current activations in license details
2. Revoke unused activations to free up seats
3. Upgrade license to allow more seats

Decryption Failed Messages

If protected code fails to decrypt:

Common Causes

• Corrupted protected file
• Invalid or expired LAT token
• License validation failure
• Missing or incorrect loader

Solutions

1. Verify LAT Token:
   • Check that LAT token exists and is valid
   • Refresh LAT if expired (use refresh endpoint)
   • Re-activate license if needed
2. Check License Status:
   • Verify license is active in customer portal
   • Check for any blocks or revocations
   • Ensure license hasn't expired
3. Verify Protected File:
   • Re-download the protected package
   • Ensure file wasn't corrupted during transfer
   • Check file permissions
4. Check Loader:
   • Ensure MemoryShield extension is installed
   • Verify extension version compatibility
   • Check loader helper file exists

Performance Optimization

Tips for optimal performance with protected code:

OPcache Configuration

Enable and configure OPcache for better performance:

; php.ini
opcache.enable=1
opcache.memory_consumption=128
opcache.max_accelerated_files=10000
opcache.validate_timestamps=0  # Production only

Memory Settings

Increase PHP memory limit if needed:

memory_limit = 256M

Runtime Overhead

Protected code has minimal runtime overhead:

• License validation happens once per request (cached)
• Decryption is performed in-memory only
• No disk I/O for decryption operations
• Performance impact is typically less than 5%

Debug Mode Usage

Enable debug mode for troubleshooting:

Enabling Debug Mode

Set environment variable:

export DEBUG_MODE=1

Or in your application:

putenv('DEBUG_MODE=1');

Debug Information

Debug mode provides:

• Detailed error messages
• License validation logs
• Decryption process information
• API call details

Common Error Messages

"This encoded file cannot be run"

Meaning: MemoryShield extension is not loaded or license validation failed.

Solution: Install MemoryShield extension and ensure license is activated.

"License validation failed"

Meaning: License key is invalid, expired, or revoked.

Solution: Check license status in customer portal and re-activate if needed.

"Device hash mismatch"

Meaning: License is bound to a different device.

Solution: Use the correct device or contact support to reset device binding.

"Maximum seats exceeded"

Meaning: All license seats are in use.

Solution: Revoke unused activations or upgrade license.

"Package encoding failed"

Meaning: Encoding process encountered an error.

Solution: Check package size limits, verify ZIP file integrity, review encoding logs.

Getting Additional Help

If you can't resolve an issue:

• Check the API Reference for detailed endpoint information
• Review your account logs in the customer portal
• Contact support at support@shieldcipher.com
• Include error messages, logs, and steps to reproduce