[Bug]: "Error: Unknown option '--debug'. Did you mean '--debug'?"

[anderseknert]

I have done the following

• I have searched the existing issues
• If possible, I've reproduced the issue using the 'main' branch of this project

Steps to reproduce

container run --debug ghcr.io/styrainc/regal:0.35.1

Current behavior

Error: Unknown option '--debug'. Did you mean '--debug'?
Usage: container run [<options>] <image> [<arguments> ...]
  See 'container run --help' for more information.

Expected behavior

container run --help tells me that the run command has a --debug flag. Trying to use that however gives me the error message in the issue title. It's a rather amusing error message, mind you! But I doubt that's intended.

If I do something like --debug=foo I'll get Error: The option '--debug' does not take any value, but 'foo' was specified. so evidently the --debug flag is recognized, it just doesn't seem to work when only provided as --debug.

My expectation would be that --debug works, or that the error message explains why it's not.

Environment

- OS: 15.5
- Xcode: 
- Container: 0.2.0

Relevant log output

Code of Conduct

• I agree to follow this project's Code of Conduct

[dcantah]

Yea.. this is a crummy UX. --debug is really a global flag and needs to be placed before run, but in the flag output it's grouped together with the other actual flags for run itself. I'll look into ways to separate the two.

[anderseknert]

Thanks! Yeah I eventually got it to work by moving it before run. But I never saw any difference in the output. Is there something more to it than adding the flag? I have a few container images that fail to start, providing very little details more than something about an XPC interrupt (I’m on my phone, can check later) and the logs don’t tell me much more either. So that’s the context :)

[dcantah]

--debug on the cli is honestly a bit dumb today, it only lights up one debug log in the builder. When you start the daemon however (container system start) there is a debug flag you can provide that lights up all the debug logs in the daemon that can be viewed with container system logs. This is where I'd investigate first.

[anderseknert]

That’s helpful, thanks! I’ll give it a shot tonight to see what I can find 👍

[anderseknert]

I saw a little more info logged now, but nothing more around the error from what I could tell.

2025-07-22 17:42:24.718990+0200 0x4f7cfd   Info        0x0                  66261  0    container-apiserver: [com.apple.container:APIServer] Handling container b88af26e-bcfc-45de-8693-3266ede5f1e9 exit. Code -1
2025-07-22 17:42:24.794437+0200 0x4f7cff   Error       0x0                  66261  0    container-apiserver: [com.apple.container:APIServer] xpc client handler connection error Connection invalid

However — and apologies for derailing a little from my original issue — removing all flags from the run command, going from this:

container run --rm --interactive --tty openpolicyagent/opa:1.6.0-static version

To this:

container run openpolicyagent/opa:1.6.0-static version

And now it seems the actual issue is logged 😃

2025-07-22 18:30:17.152705+0200 0x4fab87   Error       0x0                  66572  0    container-runtime-linux: [com.apple.container:RuntimeLinuxHelper] handler for com.apple.container.sandbox/start threw error internalError: "failed to start process" (cause: "internal error (13): create managed process: internalError: "Cannot find User '1000' in passwd file."") [uuid=2c36817e-ded4-4271-b650-dfdb5eed8096]

The Docker file does have this in it:

# Any non-zero number will do, and unfortunately a named user will not, as k8s
# pod securityContext runAsNonRoot can't resolve the user ID:
# https://github.com/kubernetes/kubernetes/issues/40958.
ARG USER=1000:1000
USER ${USER}

So that at least checks out. Not sure how I'd go on about fixing that though, and I couldn't find any previous issue reported on this. Do you think I should file one, or is there some easy fix that I could help document?

EDIT: Yes, running with --uid 0 makes it work. So I guess that issue is resolved, even if I'd still love to know if this could be made to work without an override.

[jglogan]

Looks like we're looking at two separate issues now...am I getting this right?

• The error output for container run --debug is confusing and risible, and the help output doesn't provide indication that debug is a top-level flag and needs to go before the subcommand.
• container --debug run should produce useful debugging output.

@anderseknert if that makes sense, what do you think about creating a second issue to cover the second item, and for "expected behavior" list everything that you think would be useful in the debug output?

[anderseknert]

Yeah, a mixed bag of issues here for sure :) Leaving the uid issue that got me here aside, I agree about --debug not making any (or minimal) difference for what's printed or logged is an issue in it's own right. Happy to file one for it 👍

Without meaning to pile more on to your list... 😄 The reason I reached for debug logging in the first place was how running the command below with --rm would fail with no meaningful details printed or logged:

container run --rm openpolicyagent/opa:1.6.0-static version

Whereas later and mostly by accident I learnt what the root cause was by removing that flag:

container run openpolicyagent/opa:1.6.0-static version

It seems odd that the presence of the --rm flag would have the root cause of an error not getting logged, and I'm guessing that's unintentional?

[jglogan]

@anderseknert Piling more bugs on is good, the tool is still in its infancy and it's great that you're bringing these problems up. Have you filed an issue for the run -rm issue? It looks like something that should be easily reproducible and addressable.

[anderseknert]

Sorry for the delay @jglogan!

Just upgraded to 0.4.1 and my --rm issue persists, so I have now filed an issue for that.

The root cause, which I learnt about when the --rm flag was removed, is this. That may or may not be a bug, but whatever it is, it's something that at least isn't obvious to the casual user (me)... which is arguably a bug in its own right? :)

One positive thing to mention about the 0.4.1 upgrade is that the root cause (without --rm) now gets printed directly in the output, whereas with 0.3.0 it would only be found with container system logs.

[dcantah]

The uid issue is definitely a bug. Will look

[dcantah]

Commented on the discussion. It's because we treat the uid not existing in /etc/passwd as an error today. This is not the case for containerd and other runtimes.

[keo]

Same thing happens with container start. It's a bit confusing:

$ container start --help
OVERVIEW: Start a container

USAGE: container start [--attach] [--interactive] [--debug] <container-id>

ARGUMENTS:
  <container-id>          Container's ID

OPTIONS:
  -a, --attach            Attach STDOUT/STDERR
  -i, --interactive       Attach container's STDIN
  --debug                 Enable debug output [environment: CONTAINER_DEBUG]
  --version               Show the version.
  -h, --help              Show help information.

Then I use it as advertised:

$ container start -a -i --debug 66fd9b80-0f68-4da5-aba8-4fdea8a51f3f
Error: Unknown option '--debug'. Did you mean '--debug'?
Usage: container start [--attach] [--interactive] [--debug] <container-id>
  See 'container start --help' for more information.

I get this funny error Error: Unknown option '--debug'. Did you mean '--debug'?

If I put --debug before start, ie. container --debug start -a -i .... it seems to work (although I don't see any debug messages - maybe because there are none, or maybe related to some other bug)

[jglogan]

@keo Yeah, you're seeing exactly what I commented on in #360 (comment).

Since --debug is a global option, it needs to appear before between container and the subcommand.

And the "helpful response" is just goofy.

Feel free to have a look at the CLI code and swift-argument-parser and see if there's a better way! We're working in the months to come on fixing UX glitches and inconsistencies but our little team can only work on so much 😄