Exception Occurred While Executing Put [Fixed]

Encountering an Exception Occurred While Executing Put error during Android debugging can be a frustrating roadblock for developers and enthusiasts alike. This specific error frequently arises when attempting to utilize ADB (Android Debug Bridge) commands to modify system-level settings or grant secure permissions. We understand the complexity of the Android ecosystem, particularly when dealing with system partitions and permission hierarchies. This guide provides a comprehensive, step-by-step resolution to this persistent issue, ensuring you can successfully modify system parameters without triggering fatal execution exceptions.

Understanding the Root Cause of the Exception Occurred While Executing Put

To effectively resolve the Exception Occurred While Executing Put error, one must first understand the underlying mechanisms of the Android security architecture. The error is rarely a syntax issue within the command itself; rather, it is almost always a symptom of a permission denial or an environment configuration mismatch.

The Role of WRITE_SECURE_SETTINGS Permission

The primary catalyst for this error is the lack of the WRITE_SECURE_SETTINGS permission. Android operates on a tiered security model. Standard ADB shell access grants shell user privileges, which are sufficient for many debugging tasks but fall short when attempting to write to the secure table in the Android Settings Provider. This table contains critical configuration data, including user settings for development options, lock screen configurations, and accessibility services.

When you execute a command such as adb shell settings put secure ..., the system checks if the calling process holds the WRITE_SECURE_SETTINGS permission. Since the shell user does not possess this permission by default, the Android framework throws a SecurityException, which is often translated into the “Exception Occurred While Executing Put” message in the console or terminal.

File System Permissions and SELinux

Beyond the framework-level permissions, the Android file system imposes strict access controls. The /data/secure/ and /data/system/ directories are protected partitions. On modern devices running Android 10 and higher, SELinux (Security-Enhanced Linux) is enforcing strict policies that prevent even root users from modifying certain contexts without proper labeling. If the settings binary attempts to write to a protected sector without the correct security context, the kernel will deny the request, resulting in an execution failure.

Prerequisites for Resolving the Execution Error

Before applying specific fixes, we must establish a baseline environment. A mismatch in driver versions or connection protocols is a common cause of intermittent failures that manifest as execution exceptions.

Ensuring Proper USB Debugging Configuration

The first step is to verify that USB Debugging is correctly enabled on the target device.

Navigate to Settings > About Phone.
Tap Build Number seven times to unlock Developer Options.
Enter Developer Options and enable USB Debugging.
Connect your device to your computer. When prompted on the device screen, check the box to Always allow from this computer and tap Allow.

Updating ADB and Fastboot Drivers

Outdated or generic USB drivers often fail to handle the data stream correctly, leading to “Pipe error” or “Execution exception” messages.

Windows: Utilize the Google USB Driver via the SDK Manager in Android Studio, or use the generic ADB driver provided by your device manufacturer (e.g., OnePlus drivers for OnePlus devices).
Linux/macOS: These systems generally have built-in drivers, but ensure your user group has permissions for the USB device. You may need to add your user to the plugdev group.

Verifying ADB Connection

Open a terminal or command prompt and execute:

adb devices

Ensure the device serial number appears with the status device. If it shows unauthorized, accept the prompt on the device. If it shows offline, restart the ADB server:

adb kill-server
adb start-server

The Primary Fix: Granting WRITE_SECURE_SETTINGS

The most effective solution for the Exception Occurred While Executing Put error is explicitly granting the WRITE_SECURE_SETTINGS permission to the shell environment. This bypasses the standard Android permission checks for the current ADB session.

Executing the Permission Grant Command

We do not require root access for this specific permission grant on most devices, provided you have authorized ADB access.

Open your terminal.

Enter the following command exactly:

adb shell pm grant android.permission.WRITE_SECURE_SETTINGS

This command instructs the Package Manager (pm) to grant the specific permission to the shell environment. Note that there is no visual feedback upon success; the command will simply return to the prompt.

Validating the Permission

To confirm the permission was granted successfully, we can query the settings database.

Execute:
```
adb shell settings list secure
```
If the command returns a list of settings without an “Exception Occurred” error, the permission is active.
Alternatively, check the permissions for the shell user:
```
adb shell dumpsys package android | grep WRITE_SECURE_SETTINGS
```
You should see WRITE_SECURE_SETTINGS listed under granted permissions.

Rebooting the Device (If Necessary)

In rare cases, the Android framework caches permission states. If the error persists after granting permissions, perform a soft reboot:

adb reboot

Once the device restarts, re-establish the ADB connection and attempt your original command again.

Troubleshooting Persistent Execution Exceptions

If the primary fix does not resolve the issue, the problem may lie in the command syntax, the target API level, or a locked bootloader.

Analyzing Command Syntax and Case Sensitivity

The settings command is case-sensitive and requires strict adherence to the namespace rules.

Global vs. Secure vs. System: Ensure you are targeting the correct table.
- global: Settings that apply to all users and are not backed up.
- secure: Secure settings, limited to system-imposed restrictions (requires WRITE_SECURE_SETTINGS).
- system: Settings specific to the current user profile.
Data Types: The value provided must match the expected type (integer, string, boolean). Passing a string to an integer field can trigger a FormatException which may be reported as an execution exception.

Handling API Level Restrictions (Android 10/11/12+)

Google has progressively restricted access to non-resettable device identifiers and secure settings. On Android 11 and higher, even with WRITE_SECURE_SETTINGS, certain actions are blocked by the app_ops (Application Operations) manager.

Solutions: If the target setting is restricted by app_ops, you may need to utilize adb appops set <package_name> <operation_name> allow.
Shizuku / Sui Integration: For advanced users, integrating tools like Shizuku allows ADB-permission commands to be executed via a wireless debugging interface, which sometimes bypasses stricter USB-based restrictions on modified ROMs.

The “Offline” and “Device” State Confusion

A common mistake is executing commands while the device status is unauthorized or offline. The “Exception Occurred” message can be a generic catch-all for a broken pipe connection.

Switch Protocols: If USB debugging fails, switch to Wireless Debugging (available in Developer Options).
Connect via TCP/IP:
```
adb tcpip 5555
adb connect <DEVICE_IP>:5555
```
This often stabilizes the connection and reduces execution errors.

Addressing the Specific Use Case: Replacing Google Discover with Shelf

As mentioned in the context, this error frequently appears when attempting to replace Google Discover with the Google Shelf on devices like OnePlus. This requires modifying the workspace_qsb_override setting in the secure table.

The Correct Command for Shelf Replacement

To replace Google Discover (Launcher) with the Google Shelf (Search Bar overlay), the standard command is:

adb shell settings put secure workspace_qsb_override 1

If this command triggers the Exception Occurred While Executing Put, it indicates that the WRITE_SECURE_SETTINGS permission is missing or the Launcher does not have the requisite privileges to accept the override.

Resolving the Shelf/Discover Error

Grant Permission: First, execute the grant command detailed in Section 3.
```
adb shell pm grant android.permission.WRITE_SECURE_SETTINGS
```
Verify Launcher Status: Ensure the default launcher is set to “Launcher3” or the system default, not a third-party launcher like Nova or Microsoft Launcher. The command targets the system launcher overlay.
Revert Changes: If the command fails or causes the launcher to crash, revert to the default immediately:
```
adb shell settings delete secure workspace_qsb_override
```

Advanced Troubleshooting: Root Access and System Modifications

For users with rooted devices, the Exception Occurred While Executing Put error may indicate a mismatch in system partition mounts or SELinux policy enforcement.

Executing Commands with Root Privileges

If the device is rooted, use the su command to elevate the shell session before executing the settings command.

adb shell
su
settings put secure <key> <value>

The su binary grants full root access, bypassing the WRITE_SECURE_SETTINGS check because the root user has write access to the underlying database files (/data/system/users/0/settings_secure.xml).

Checking SELinux Enforcing Mode

SELinux can block ADB commands even with root access if the context is incorrect.

Check the current mode:
```
adb shell getenforce
```
If the output is Enforcing, and you are encountering persistent errors, you may temporarily set it to Permissive for testing (requires root):
```
adb shell setenforce 0
```
If the command works in Permissive mode but fails in Enforcing mode, you have identified an SELinux denial. You will need to check the audit logs (/sys/fs/selinux/avc) to create a custom policy rule.

Recompiling the Settings APK (Magisk Modules)

If you are using a custom ROM or a heavily modified system (like OxygenOS on OnePlus), the settings binary might be modified. In such cases, the binary might have hardcoded restrictions.

Magisk Solution: Modules like “Systemless Hosts” or “Permissions Manager” can override these restrictions.
Magisk Module Repository: We recommend visiting the Magisk Module Repository to find modules specifically designed to manage system permissions and overlay overrides. These modules often patch the framework-res.apk to allow persistent permission grants without repeated ADB commands. You can download these modules at Magisk Modules.

Common Error Messages and Their Meanings

When debugging, recognizing the specific error message helps isolate the fix.

“java.lang.SecurityException: Permission denial”

This confirms the lack of WRITE_SECURE_SETTINGS. The stack trace will usually point to SettingsProvider. The fix is strictly permission-related (Section 3).

“java.lang.IllegalArgumentException: You cannot change a immutable value”

This occurs if the setting key is read-only or locked by the carrier/OEM. For example, modifying global settings restricted by the carrier will trigger this. In this case, the “Exception Occurred” is not a permission issue but a policy restriction.

“No such file or directory” (Pipe Error)

This is a connectivity issue. It indicates the ADB daemon on the device has dropped the connection. Restart the server and check the USB cable quality.

Best Practices to Prevent Future Execution Errors

To ensure long-term stability and avoid repeated exceptions, adhere to these best practices.

Use Scripts for Batch Operations

If you are applying multiple settings changes (e.g., customizing a new device setup), create a batch script (.bat for Windows, .sh for Linux/Mac). This ensures that commands are executed sequentially and reduces the chance of human error in typing.

Verify Settings Keys Before Execution

Before executing a put command, verify that the key exists and is writable. You can do this by querying the key:

adb shell settings get secure <key_name>

If this returns null or the value, the key exists. If it returns an error, the key may be deprecated or specific to a higher API level.

Backup Current Settings

We strongly advise backing up the current state of the secure table before making changes. This allows for easy restoration if an exception occurs.

adb shell settings list secure > settings_backup.txt

You can later parse this file to restore values.

Conclusion

Resolving the Exception Occurred While Executing Put error requires a methodical approach, starting with the fundamental granting of the WRITE_SECURE_SETTINGS permission. Whether you are attempting to restore Google Discover, enable developer hidden settings, or customize the UI overlay on a OnePlus device, the failure is almost always permission-related or due to a broken ADB connection. By following the detailed steps outlined above—verifying drivers, granting explicit permissions, and understanding the underlying security architecture—you can successfully execute ADB commands without error. For users requiring deeper system modifications, utilizing the Magisk Module Repository offers robust solutions for persistent system-level changes.

We ensure that by adhering to these protocols, your ADB execution environment will be stable, secure, and free of the dreaded execution exceptions.

You also may like 〣〣