Termux:API commands hang due to "Invalid action: com.termux.service_api" - Proposed Broadcast Fix

[ssibb]

termux_api_shim.py

Disclaimer:
This report has been prepared by Gemini 3.0. It has successfully solved the issue for me and, while I do not have a complete understanding of what it has done, I hope this might be useful anyway.
Gemini has been debugging a user's local Termux environment where termux-api commands were failing. I am reporting the specific findings, logs, and a confirmed working solution derived from this session to assist the mantainers. Happy to help further, if needed.

Environment

• Device: Android (Xiaomi/MIUI environment detected in logs)
• Termux App Version: 0.118.3 (F-Droid signature)
• Termux:API App Version: 0.53.0 (F-Droid signature)
• termux-api package: 0.59.1 (aarch64)

The Issue

Execution of any API command (e.g., termux-battery-status, termux-vibrate) hangs indefinitely. The commands never return output and eventually timeout if a timeout is enforced.

Logcat Analysis:
When running termux-battery-status, the system log shows TermuxService rejecting the intent:

ActivityManager: Logging startService for com.termux, ... intent=Intent { act=com.termux.service_api cmp=com.termux/.app.TermuxService ... }
Termux:TermuxService: Invalid action: "com.termux.service_api"

It appears the current termux-api binary (C helper) attempts to start com.termux.app.TermuxService with the action com.termux.service_api. The main Termux app's service implementation (in onStartCommand) falls through or explicitly logs this action as invalid/unhandled.

Investigation & Attempts

1. Standard Execution: Confirmed am startservice -a com.termux.service_api ... fails with the log error above.
2. Service Execute: Tried am startservice -a com.termux.service_execute ... (which is handled by TermuxService), but this expects a plugin execution context/runner and did not successfully bridge to the API logic.
3. Targeting the Receiver directly:
   We analyzed the Termux:API manifest and dumpsys. com.termux.api.TermuxApiReceiver is a registered receiver. Although declared with android:exported="false", it shares the same signature and user ID as the main Termux app, allowing interaction via root or same-user contexts.

The Solution (Verified)

We created a Python shim to replace /data/data/com.termux/files/usr/libexec/termux-api.

Instead of calling am startservice targeting the main app, the shim calls am broadcast targeting the API receiver directly.

Old Command (failing):

am startservice --user 0 -n com.termux/com.termux.app.TermuxService -a com.termux.service_api --es api_method BatteryStatus ...

New Command (Working):

am broadcast --user 0 -n com.termux.api/.TermuxApiReceiver --es api_method BatteryStatus ...

Verification

We verified this fix locally by replacing the libexec/termux-api binary with a Python script implementing the broadcast logic.

• BatteryStatus: Returns JSON correctly.
• Vibrate: Vibrates the device (permissions granted).
• Clipboard: Works correctly (implemented stdin reading in the shim to pass to the input socket).
• JobScheduler: Successfully lists and schedules jobs.

Recommendation

The issue seems to be a disconnect between how the termux-api C binary invokes the service and how the TermuxService (in the main app) expects to be called (or has stopped supporting service_api).

Updating the termux-api.c client to use an Intent Broadcast targeting com.termux.api/.TermuxApiReceiver (rather than starting the main TermuxService) appears to resolve the issue entirely on this version combination.

Key technical note for the fix:
If implementing this in the C binary, ensure the input socket handling (stdin) is maintained, as the TermuxApiReceiver logic appears to handle the socket connections correctly once triggered via Broadcast.

[sylirre]

Can you point in source code where exactly issue is present?

https://github.com/termux/termux-api-package/blob/0e3f9222eea7760c76ea6368dadbdf884ab85fbf/termux-api.c#L263-L277 has this:

    child_argv[0] = "am";
    child_argv[1] = "broadcast";
    child_argv[2] = "--user";
    child_argv[3] = "0";
    child_argv[4] = "-n";
    child_argv[5] = "com.termux.api/.TermuxApiReceiver";
    child_argv[6] = "--es";
    // Input/output are reversed for the java process (our output is its input):
    child_argv[7] = "socket_input";
    child_argv[8] = output_address_string;
    child_argv[9] = "--es";
    child_argv[10] = "socket_output";
    child_argv[11] = input_address_string;
    child_argv[12] = "--es";
    child_argv[13] = "api_method";

Make sure you have everything up to date.

If you have an error, we would like to see raw logs instead of Gemini AI interpretation.

[ssibb]

Hi, thanks for the reply. I can't, but I can provide the log and try again an update (with no help). Also, the version I'm Using is from fdroid on a recent device (Poco X7 Pro). Yesterday I downloaded termux and termux-api from github and worked fine, but that happened with another, older, phone (Xiaomi Mi A1, Android 8). I can't backup, uninstall and reinstall from github in the near future in my current device.

Here it is the row from Logcat reader (manually extracted this morning):

[2026-03-06 07:43:34.955 Uid(value=10434):17377:17377 E/Termux:TermuxService]
Invalid action: "com.termux.service_api"

..and here the transcript from the console (the standard version doesn't work, see I had to ^C, the script made by gemini works)

~/gemini $ apt install termux-api
termux-api is already the newest version (0.59.1).
Summary:
Upgrading: 0, Installing: 0, Removing: 0, Not Upgrading: 19
~/gemini $ apt reinstall termux-api
Summary:
Upgrading: 0, Installing: 0, Reinstalling: 1, Removing: 0, Not Upgrading: 19
Download size: 0 B / 27.3 kB
Space needed: 0 B

(Reading database ... 50121 files and directories currently installed.)
Preparing to unpack .../termux-api_0.59.1_aarch64.deb ...
Unpacking termux-api (0.59.1) over (0.59.1) ...
Setting up termux-api (0.59.1) ...
~/gemini $ termux-battery-status
^C
~/gemini $ cp termux_api_shim.py /data/data/com.termux/files/usr/libexec/termux-api
~/gemini $ chmod +x /data/data/com.termux/files/usr/libexec/termux-api
~/gemini $ termux-battery-status
{
"present": true,
"technology": "Li-poly",
"health": "GOOD",
"plugged": "UNPLUGGED",
"status": "DISCHARGING",
"temperature": 25.6,
"voltage": 3912,
"current": 434000,
"current_average": 0,
"percentage": 59,
"level": 59,
"scale": 100,
"charge_counter": 3316000,
"cycle": 64
}
~/gemini $

---

Here below the Gemini's opinion, when prompted with your reply:

The installed termux-api binary (v0.59.1) in this environment is
not using the code you linked. It is using the legacy
startService method, which is why it fails.

Here are the raw logs and binary analysis from the actual device
proving this:

1. Raw Logcat Output
   The logs clearly show the termux-api process sending a
   startService Intent with action com.termux.service_api, which
   TermuxService rejects.

1 03-04 22:00:45.790 2244 3567 D ActivityManager: Logging
startService for com.termux, stopped=false, firstLaunch=false
intent=Intent { act=com.termux.service_api
cmp=com.termux/.app.TermuxService (has extras) },
r.app=ProcessRecord{e10b056 5584:com.termux/u0a434}
2 03-04 22:00:45.795 5584 5584 E Termux:TermuxService: Invalid
action: "com.termux.service_api"

2. Binary Strings Analysis
   Running strings on the installed binary
   (/data/data/com.termux/files/usr/libexec/termux-api) confirms it
   contains the old startservice and com.termux.service_api
   strings, not the broadcast logic seen in your source link.

1 $ strings /data/data/com.termux/files/usr/libexec/termux-api
grep -E "startservice|broadcast|service_api"
2 startservice
3 com.termux.service_api
(Note: "broadcast" is missing)

3. Version Mismatch

• Installed Version: 0.59.1 (from termux.net stable repo)
• Repo Status: apt list --upgradable does not show an update
  for termux-api. The system thinks 0.59.1 is the latest
  version.

Conclusion:
The installed package termux-api (v0.59.1) is outdated compared
to the source code you linked (which uses broadcast), likely due
to the repository configuration pointing to the legacy
termux.net. The issue is that the package manager is serving an
old binary that is incompatible with the current Termux app.

My "Shim" solution essentially manually applied the update that
should have been present in the package: switching from
startService to broadcast.

---

Last comment from me (human): github shows release 0.53, and that the one working on my older phone, while termux api are 0.59.1, can this be a strange version mismatch? Strange because, if anything, I would expect github to have an equal or more recent version compared with apt, but that not what numbering is suggesting.

[sylirre]

I just wanted to point that Gemini's reply is not anywhere close to reality.

If something like said by Gemini would be true, we would get mass-reporting about Termux:API failure. But that's not the case.

Termux:API app and termux-api package don't use synchronized versioning and there is absolutely zero chance that will be some mismatch.

[sylirre]

I digged GitHub about com.termux.service_api and found this: https://github.com/termux-play-store/termux-packages/blob/main/packages/termux-api/termux-api.c.patch

Your app maybe from F-Droid, but packages definitely associated with Play Store release. Please don't report issues about something that we have no control over.