Troubleshooting

fetch failed

The CLI could not reach the configured Server. Check the URL, DNS, TLS certificate, proxy, and whether the Server health endpoint is reachable from the same machine:

curl --fail https://server.example.com/health
ods client doctor

ods up checks this endpoint before reporting that the background Client is running. A local service can be active while DNS or outbound Internet access is unavailable.

Machine is offline

The machine record exists but its Client connection is not active:

ods client status
ods up

For a foreground Client, run ods client start and keep the process alive. Also verify outbound HTTPS/WSS access to the Server.

client_upgrade_required

The machine authenticated with an incompatible protocol and remains offline. On that machine:

ods client update
ods client doctor

Only patch updates inside the installed pre-1.0 minor line are automatic. Follow the release migration guide for a minor version change.

CLI still shows the previous version

More than one package manager may have installed ods. Find which executable appears first:

type -a ods

Update @odyshell/cli with the package manager that owns the first result, then restart each Profile with ods down --profile <name> followed by ods up --profile <name>.

client_already_enrolled

The selected configuration already contains a machine identity. Start it without enrollment options:

ods up

To enroll a separate identity, choose a new Client Profile:

ods up --profile company <enrollment-options>

Do not overwrite or copy an existing Machine identity.

client_config_server_mismatch

The selected local identity belongs to another Server. Choose an isolated Profile:

ods up --profile company <enrollment-options>

List local identities with ods profiles ls, then remove a known unused Profile with ods profiles remove <name>. Use ods reset --yes only when every local Profile on that host should be deleted.

machine_ping_timeout

The Server knows the machine connection but did not receive the end-to-end pong in time. Check Client logs, reconnect it, and confirm that Server and Client versions match.

Task or Command denied

Compare the requested Command with the Machine's Local Policy: the Organization and Agent must match, the Task and Command concurrency limits must have capacity, and the timeout and output limits must not be exceeded. Also check Agent credential expiry, Machine assignment, absolute working-directory validity, and operating-system permissions.

A Command needs more operating-system authority

Odyshell does not configure sudo or elevate a Command. Change the dedicated Linux user's resources outside Odyshell only after reviewing the resulting authority. Prefer a narrowly owned file, service API, or dedicated wrapper over root or broad group membership.

A command may still be running after a Client crash

Graceful Task closure and cancellation terminate the active process group. Commands use detached process groups. Without a separate process supervisor, an abrupt Client crash can leave a command running until it exits by itself or is stopped by the machine owner or operating system. After restart, Odyshell reports the execution result as unknown instead of assuming the command stopped.

If the Client reports authority_termination_unconfirmed, it has quarantined the local Profile and will refuse to reconnect it after a service restart. Inspect the machine for surviving processes, then remove and re-enroll that Profile to replace its local identity and state.