Troubleshooting

Start by separating local command errors from registry failures. The CLI keeps usage, configuration, and resolver failures distinct, writes diagnostics without credentials, and returns a stable exit code for each category.

The command is rejected

Run the relevant help command:

./zig-out/bin/z-oci --help
./zig-out/bin/z-oci resolve --help

Put global options before the command:

./zig-out/bin/z-oci --ca-bundle ./ca-bundle.pem resolve ubuntu:22.04

Put command options after the command and before the image. --platform is available for resolve and inspect, not validate. validate also requires an exact image@sha256:<64-hex-digest> reference.

Usage errors return exit code 5. Help and version output return exit code 0.

Authentication fails

The bare library Config{} is anonymous. Inject credential_provider or credential_sources for a library call. The CLI process adapter injects its environment map, Docker configuration discovery, and helper I/O for that invocation; credentials are not accepted as command-line arguments.

For environment credentials, verify Z_OCI_REGISTRY_HOST, Z_OCI_REGISTRY_USER, and Z_OCI_REGISTRY_TOKEN. The configured host must match the requested registry. For Docker credentials, check DOCKER_CONFIG, HOME, or USERPROFILE, then check the registry-specific helper, inline auths, and global credsStore in the documented order. See Credentials for the exact source rules.

A helper error is terminal for that configured helper path. It does not silently fall back to anonymous access. In library code, keep borrowed environment maps, Docker JSON, and helper I/O alive until the call returns.

Authentication failures return exit code 2. A 401 from a registry may also mean that credentials are required, not that the registry is unreachable.

HTTPS or certificates fail

Confirm that --ca-bundle or Config.ca_bundle_path points to a readable certificate-only PEM bundle. A custom bundle replaces the OS trust bundle rather than merging with it. Private-key PEM blocks are rejected, and POSIX bundles writable by other users are rejected.

The helper timeout controls credential-helper I/O only. It does not set a timeout for manifest, token, or general registry requests. See Platform and limits for timeout scope and platform boundaries.

Certificate and other local configuration failures return exit code 6. The JSON error code identifies the specific configuration failure, such as ca_bundle_file_not_found or ca_bundle_invalid.

The registry request fails

Use the text error or request JSON to distinguish the failure:

• Exit 1, not_found: the requested manifest or tag was not found.
• Exit 2, auth_failed: authentication or token exchange failed.
• Exit 3, rate_limited: the registry rejected the request for rate limits after the configured retries.
• Exit 4, network_error: a transport or retryable registry failure remained.
• Exit 7, digest_mismatch or unsupported_algorithm: digest verification failed.
• Exit 8, content_type_mismatch: the response was not an accepted manifest type.
• Exit 9, manifest_parse_error, response_too_large, or depth_limit_exceeded: the manifest content could not be processed.
• Exit 10, timeout: a configured operation timed out.
• Exit 12, unexpected: an unclassified process failure occurred.

The complete code list and output shapes are in CLI. The library returns these resolver failures as tagged ResolveError values instead of process exit codes.

A platform cannot be selected

Use inspect to view top-level manifest or index metadata, then pass an exact os/arch[/variant] filter to resolve or inspect:

./zig-out/bin/z-oci inspect --format json ubuntu:22.04
./zig-out/bin/z-oci inspect --platform linux/amd64 --format json ubuntu:22.04

Omitting a variant accepts any candidate variant. Supplying one requires a case-insensitive match. A missing platform is different from a missing reference:

• platform_required means a multi-arch document needs a platform selection.
• platform_not_found means the requested platform is absent.
• depth_limit_exceeded means nested index traversal exceeded four child levels.

Library filters can also use os_version; it uses dot-segment prefix matching. os_features is preserved metadata and is not a selector constraint. Platform failures return exit code 11 in the CLI.

Output goes to the wrong stream

Successful output, help, and version go to standard output. Text diagnostics and --verbose timing go to standard error. JSON failures go to standard output so a script can parse them. Use --format json when a caller needs structured failure data.