A host-exec wrapper in the shared home fails with a misleading message

distrobox-host-exec(1) documents this way of reaching a host command from inside a container:

Alternatively, you can symlink a command name to "distrobox-host-exec" and then call that command by its name on the host, while inside of a container.

Following exactly that, and putting the symlink in ~/.local/bin - the obvious place for a user-owned command - the call fails with a message that describes the opposite of what happened:

You must run  dbx-symlink-probe inside a container!

It was run inside a container. The message even carries the symlink's own name, which makes it read as if that command were the problem.

What is actually going on

~/.local/bin lives in the home directory, which distrobox shares with the host, and it is on the host's PATH on most distributions. So:

1. inside the container, PATH finds the symlink and distrobox-host-exec runs, as intended;
2. host-spawn runs the command on the host, where PATH finds the same symlink;
3. distrobox-host-exec starts again, this time on the host, and correctly refuses - printing the message above.

The guard stops it after one extra hop, so nothing spins forever. But the message points at the one thing that is not wrong, and nothing in the output mentions the host, or the symlink, as the source of the second call.

Reproducing it

Throwaway name, so nothing real is shadowed:

$ ln -sf /usr/bin/distrobox-host-exec ~/.local/bin/dbx-symlink-probe
$ echo "$PATH" | tr ':' '\n' | grep -c "^$HOME/.local/bin$"
1
$ distrobox enter mybox -- bash -lc 'dbx-symlink-probe echo test'
You must run  dbx-symlink-probe inside a container!

A wrapper script instead of a symlink behaves the same way, and a counter shows the two hops:

$ printf '%s\n' '#!/bin/sh' 'echo x >> /tmp/dbx-count' 'exec distrobox-host-exec dbx-loop-probe "$@"' > ~/.local/bin/dbx-loop-probe
$ chmod +x ~/.local/bin/dbx-loop-probe; : > /tmp/dbx-count
$ distrobox enter mybox -- bash -lc 'dbx-loop-probe; echo "exit: $?"'
You must run  distrobox-host-exec inside a container!
exit: 126
$ wc -l < /tmp/dbx-count
2

Put the same wrapper where the host has nothing on PATH and it works as documented:

$ distrobox enter mybox -- env PATH=/var/tmp/wrappers:$PATH docker --version
Docker version 29.7.2, build a7dcaa6

Suggestions

• Say where the second call came from. When distrobox-host-exec finds itself on the host, the message could give the usual reason: the command name it was called as is on the host's PATH too, so the host resolved the same symlink or wrapper again.
• Say it in the manual. The sentence quoted above is the only guidance, and it does not mention that the symlink must be somewhere the container has on PATH and the host does not - which rules out the shared home, the first place anyone will try.

Version: distrobox 1.8.2.5, podman 5.8.4, Fedora 44.