Startup and diagnostics

This page covers what happens when DataMind Oda starts: what you see while it loads, 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. The later sections are for the people who launch Oda from a command line, run it in a serving mode, or debug a start that fails.

The loading screen

When you open DataMind Oda, it loads its plugins, the parts it is built from, before its interface appears.

• While Oda starts, you see the DataMind Oda wordmark, the text Loading plugins… and a spinner. The spinner's arc grows as more plugins load.
• Oda shows its interface only after every plugin has loaded. You see this screen every time you open Oda, including the first time after installing it.
• The loading screen does not depend on the app's interface, so a plugin that fails stays visible, with its report, instead of a blank screen.

If a plugin cannot load, Oda keeps the screen and reports the failure under the title Failed to load plugins, listing each plugin that failed and the failure report. Plugins that loaded are not listed. Oda does not open with plugins missing: to retry, close Oda and open it again. If the same failure comes back, keep the message and contact your administrator; When DataMind Oda will not start covers the next steps.

Once Oda is open, Settings > Built-in plugins lists the plugins loaded on this computer. A failure that comes up later, after Oda has opened, appears there instead of stopping the app; see Built-in plugins.

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. The shipped templates are web, headless, acp, sdk and sdk-minimal; Oda profiles and launchers describes what each serves, and 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, is not asked to start, so it 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:

• failed to import: the component could not be imported.
• disabled expression failed: <detail>: the component's disable condition could not be evaluated.
• pending (waiting for service: X): the component is still waiting for a service another component provides.

Other outcomes:

• 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.

Keep the output as it is: shown text is already written in Oda's wording, and Diagnostic text and logs explains those rules.

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; Oda's home folder and settings files covers the 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. Proxy and network settings covers how they are read.
• 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.

Flags and the command line

• A flag wins over the configuration. oda --profile web --port 8080 serves on port 8080 even when the configuration names another port, and the rule holds when the value is written as an expression.
• Read once, then frozen. Flags are resolved when Oda starts, so a later configuration reload never resets them, and any part of Oda can read the same line without consuming it.
• Help and refusals. --help prints the help and exits with code 0, without starting anything. A rejected flag value prints an error and exits with a code other than 0.
• A literal double dash. A literal -- needs the doubled form: -- --.

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. A patch that names an entry the profile does not have has nothing to change; the warning carries the layer's label, oda: [<layer>] <message>, its message reads patch: entry "<name>" not found, and the start continues.
• A settings file must hold a list. A file that is empty, or holds only comments, fails the next start. To switch off what the file adds, keep its header lines and leave an empty list: []. The Oda 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, at the start, 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. What can apply live is on Hot reload.

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).
3. Print the config dump (--dump-config) to see the configuration Oda composed, with each source named (# == <label>, plus , patched by <layers> where a later layer changed a row). A patch that targets nothing is reported with its layer label and skipped. A configuration that cannot be read or parsed stops the dump with failed to read config or failed to parse config.
4. Print the schema dump (--config-schema-dump) when a component failed to import. It lists every declared entry with a status, schema, partial, absent, unsupported or error, and marks the report incomplete where an entry cannot be read cleanly. It never prints configuration values or the sources of 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 does Failed to load plugins mean, and what do I do?

One or more plugins could not load, so Oda could not open its interface; the screen lists the plugins that failed. Close Oda and open it again to retry. If the same failure comes back, keep the message and contact your administrator.

Can I use Oda while a plugin is missing?

No. Oda waits for the full set of plugins before its interface appears. A failure that comes up later, after Oda has opened, is different: it appears in Settings > Built-in plugins instead of stopping the app.

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 steps in Checking a failed start.

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 is a component listed as waiting for a service?

It has not activated because a service it needs, named in pending (waiting for service: X), has not been provided. The Plugins waiting for services (N): table pairs each such component with the services it is missing.

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, where its code and instructions load from, or how it reaches the network. 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.

Which wins, a command-line flag or the settings file?

The flag. A flag wins over the configuration, even when the value is written as an expression, and it is resolved once at start, so a later reload never resets it.

Why will Oda not start from an empty settings file?

A settings file must hold a list. A file that is empty, or holds only comments, fails the next start. To switch off what the file adds, keep its header lines and leave an empty list: [].

My profile bundle could not be loaded. What now?

Oda skips the bundle and keeps its selection, so a later start tries it again. Repair the bundle, or remove it from the profile's selections.

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.