Startup and diagnostics

This page covers what happens when DataMind Oda starts: the components a run needs, what its output says when one of them fails, where its environment values come from, and which changes need a restart. It is for the people who launch Oda from a command line, run it in a serving mode, or debug a start that fails.

What a start does

• One profile per run. Oda starts the profile you name for the run: the profile lists the components to load, Oda's own pieces plus the plugin bundles that profile adds. Command line and flags covers how a profile is named.
• Every component starts, or reports why not. A component that needs a service another provides waits for it to arrive; a component that cannot start reports the reason.
• Some components are required. Oda treats these as required: the agent loop, the web server, the module and connection layers, the headless runner, the automation face and the SDK server. When one of them is asked to start and cannot activate, the whole start fails.
• The rule follows what the run counted on. A required component that a profile leaves out, or turns off, does not fail the start.
• A failed start is closed cleanly. Oda closes the components it already started, prints its diagnosis once, saves the full startup diagnostics, and exits with code 1. Nothing is left half-running.
• Optional failures do not stop the run. A component that fails but is not required is left out; everything else keeps starting, and the output warns about it (see below).

When a start fails

A failed start prints its diagnosis once. The output reads, in order:

1. A headline with the count: oda: startup failed: N required plugin(s) did not activate.
2. The failing components, under Failed plugins (N):, one line per component with its reason; a (required) marker sits beside the required ones.
3. Components still waiting for a service, under Plugins waiting for services (N):, as a table pairing each component with the services it is missing.

Reasons you may see on a failing line: a component that could not be imported (failed to import), a component whose disable condition could not be evaluated, or one still waiting for a service (pending (waiting for service: X)).

• Only optional components failed? The run continues, and the output warns oda: warning: N entry/entries did not activate; the lines after the warning name what was left out and why.
• A failure before the components could load reads oda: fatal load failure: with the failure's stack. Oda exits with code 1 after a short bounded cleanup wait; a cleanup that gets stuck delays that exit but never cancels it.

The environment layers

Oda reads its environment from three places. Highest first:

1. The environment you launch Oda with.
2. A .env file in the folder you launch from.
3. A .env file in the Oda home folder.

• A file never replaces the environment. A value the launching environment already sets wins over both files.
• Both files are read before either is applied. A refused file never leaves anything half-applied.
• Some variables may not come from a file. A file may not set the variables that only the launching environment may set: PATH and the names that decide how Oda starts, where its code and instructions load from, or how it reaches the network. The refusal names the variable: oda: <path> sets "<NAME>", which only the launching environment may set. The fix it offers is to export the value where you launch Oda, or to put it in the home folder's file, which does not travel with a project folder.
• Proxy settings are the exception. HTTP_PROXY, HTTPS_PROXY, ALL_PROXY and NO_PROXY are accepted from the home folder's .env only; a file in the folder you launch from may not set them.
• The telemetry switch reads any non-empty value as off. 0 and false included; a privacy switch prefers off by mistake to on by mistake, and a profile that does not include telemetry needs no switch.

Profiles, bundles and patches

• A bundle that will not load is skipped. Its selection stays, so a later start tries it again. The message names it: Selected profile bundle "<name>" could not be loaded; repair or remove its bundle selection. While a profile loads, the same skip warns as skipping profile bundle "<name>": <error>.
• A patch that targets something missing is skipped with a warning. The warning carries the layer's label, oda: [<layer>] <message>, and the start continues. The profile settings file covers the file these patches live in.

How Oda finds each package

• One resolution for the whole process. Which copy of every package loads is decided once, and every part of Oda reads through that decision.
• The layers it looks through, in order: the installation's private layer, the profile's own folder, shared layers, then the home folder.
• Linked plugins keep what is theirs. A plugin linked from a folder takes the shared packages from the running installation and its own dependencies from its folder.
• Some changes cannot reach a running process. A change that would point a name at a different folder, or replace, remove or override a local package, is refused with requires a process restart. Make the change, then start Oda again.

Checking a failed start

1. Read the headline, then the failing components; start with the first reason in the list.
2. If the output refused a .env file or named a variable, fix the environment first (see The environment layers above).
3. Print the config dump (--dump-config) to see the configuration Oda composed, with each source named (# == <label>, plus , patched by <layers> where a patch layer changed a row). A patch that targets nothing is reported and skipped.
4. Print the schema dump (--config-schema-dump) when a component failed to import: it lists a status for every declared schema so you can see whether it could be read, and it never prints values or expressions. Command line and flags covers both dump flags.
5. If a bundle was skipped, repair it or remove its selection. If a start keeps failing the same way, keep the full output for DataMind support. For messages outside a start, see Updates and troubleshooting.

Questions, answered

What is required for Oda to start?

The agent loop, the web server, the module and connection layers, the headless runner, the automation face and the SDK server. When one of them is asked to start and cannot activate, the whole start fails. A required component that a profile leaves out or turns off does not fail the start.

Oda stopped with a startup failed line. What should I read first?

Start with the headline: it counts the required components that did not activate, and the list below it names each failing component with its reason, marked (required) where it applies. If the output also refused a .env file, fix the environment first; then use the checks in Checking a failed start above.

Oda started, but warned that some entries did not activate. Is something missing?

Yes: some optional components were left out. The run continues without them and everything else keeps working. The warning reads oda: warning: N entry/entries did not activate, and the lines after it name what was left out and why.

Why did Oda refuse my .env file?

A file may not set the variables that only the launching environment may set: PATH and the names that decide how Oda starts. The refusal names the variable, and the fix is to export the value where you launch Oda or to move it to the home folder's .env.

Which .env file wins when both set the same value?

The file in the folder you launch from wins over the home folder's file. And a value the launching environment already sets wins over both.

Where should proxy settings go?

In the launching environment or in the Oda home folder's .env. A file in the folder you launch from may not set HTTP_PROXY, HTTPS_PROXY, ALL_PROXY or NO_PROXY; only the home folder's file may.

My profile bundle could not be loaded. What now?

Oda skips the bundle and keeps its selection, so a later start tries it again. The message names it: Selected profile bundle "<name>" could not be loaded; repair or remove its bundle selection. Repair the bundle, or remove it from the profile's selections.

Why does pointing a linked plugin somewhere else need a restart?

Oda decides which copy of each package loads once, for the whole process, and that decision cannot be changed under a running process: a change that points a name at a different folder, or replaces, removes or overrides a local package, is refused with requires a process restart. Make the change and start Oda again. What can apply live is on Hot reload.

Oda will not start. How do I see the configuration it was given?

Print the config dump (--dump-config) for the configuration Oda composed from its layers, and the schema dump (--config-schema-dump) to see whether each declared schema could be read; the schema dump never prints values or expressions. Both flags are on Command line and flags.

After a failed start, is anything still running?

No. A failed start closes the components it already started before it exits, so nothing is left half-running. Fix the cause and start the profile again; the full output is printed once and the startup diagnostics are saved.