Startup and diagnostics

Every run of DataMind Oda begins with a start: Oda loads the parts of its setup before it can do any work. This page is the reference for that start: the parts it needs, what its output says when one of them fails, where its environment values come from, and how to read the reports it leaves behind.

What a start does

• One profile per run. Every run starts from one profile, the named set of parts to load. The shipped templates are web, headless, acp, sdk and sdk-minimal; Oda profiles and launchers describes what each serves.
• Every part that can start, starts. Oda keeps every component that can activate and reports the ones that cannot.
• Some parts are required. A start fails as a whole when a required part is asked to start and cannot activate. The required parts are the agent loop, the web server, the module and connection layers, the headless runner, the automation face and the SDK server.
• The rule follows what the run counted on. A required part that the profile leaves out, or turns off, does not fail the start; only a required part that was asked to start and could not activate does.
• One resolution for the whole run. Which copy of every package loads is decided once, at the start, and every part of the run reads through that decision. A change that would point a name at a different package or folder is refused while Oda runs with requires a process restart; Hot reload: what changes live covers what waits for the next start.
• A failed start closes cleanly. When a required part cannot activate, Oda closes the parts it already started, prints its diagnosis once, saves the full startup diagnostics, and exits with code 1. Nothing is left half-running.

When a start fails

The diagnosis is printed once, in this order:

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

Reasons you may see on a failing line:

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

If the failure happens before Oda's parts can load at all, the output reads oda: fatal load failure: <stack>, with the failure's stack. Oda still 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 Reading Oda's diagnostics explains those rules. Working through a failed start walks through one step by step, and Troubleshooting covers what to send when a message keeps coming back.

Warnings that do not stop a start

A start that is missing only optional parts continues, and reports them instead:

• Optional parts. The output warns oda: warning: N entry/entries did not activate, and the lines after it name what was left out and why. The other parts keep starting.
• Skipped patches. A patch that names an entry the profile does not have has nothing to change; it is skipped with a warning that carries the layer's label, oda: [<layer>] <message>, and the start continues. The profile settings file covers the file these patches live in.
• Skipped bundles. A bundle that cannot be loaded is skipped, and its selection is kept so a later start tries it again: Selected profile bundle "<name>" could not be loaded; repair or remove its bundle selection.

Where the environment values come from

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 launching environment. A value the launch environment already sets wins over both files.
• Both files are read before either is applied, so a refused file never leaves anything half-applied.
• Some names cannot come from a file. A file may not set PATH or 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 suggests is to export the value where you launch Oda, or to put it in the home folder's .env, 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; Proxy and network settings covers how they are read.
• The telemetry switch turns telemetry off with any non-empty value, 0 and false included; this switch prefers off by mistake to on by mistake, and a profile that does not include telemetry needs no switch.

Checking the configuration a start used

Two reports show what a start was given, without starting anything:

• The configuration dump. It prints the settings as Oda composes them, with each source named in comments: # == <label>, or # == <label>, patched by <layers> when a later layer changed the 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.
• The schema dump. It lists the schema of every declared entry with a status: schema, partial, absent, unsupported or error, and it marks the report incomplete where an entry cannot be read cleanly. It never prints configuration values or the sources of expressions.

The Oda command line covers the flags that print both dumps.

Questions, answered

When does a start print a fatal load failure instead of a failure report?

When the failure happens before Oda's parts can load at all. The line carries the failure's stack, and Oda still exits with code 1, after a short bounded cleanup wait; a cleanup that gets stuck delays that exit but never cancels it.

Why did a required part that my profile leaves out not fail the start?

Oda fails a start only over a required part that was asked to start and could not activate. A required part that the profile leaves out, or turns off, is not asked to start, so it does not fail the start.

What is the difference between a failed start and the activation warning?

A failed start names required parts and stops the run: Oda closes what it already started and exits with code 1. The activation warning oda: warning: N entry/entries did not activate names optional parts that were left out, while the run continues without them.

What do the reasons after a failing part mean?

failed to import means the part could not be imported. disabled expression failed: <detail> means its disable condition could not be evaluated. pending (waiting for service: X) means it is still waiting for a service another part provides.

Why is a part listed as waiting for a service?

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

Can any value go in a .env file?

No. A file may not set PATH or the names that decide how Oda starts, where its code and instructions load from, or how it reaches the network; such a line is refused, and the refusal names the variable. The fix it suggests is to export the value where you launch Oda, or to put it in the home folder's .env, which does not travel with a project folder.

How do I switch telemetry off?

Set the telemetry switch to any non-empty value where you launch Oda: 0 and false count as off as well, because this switch prefers off by mistake to on by mistake. A profile that does not include telemetry needs no switch.

Why did Oda skip a patch before starting?

Because it names an entry the profile does not have, so there is nothing for it to change. The warning carries the layer's label, oda: [<layer>] <message>, and the start continues.

What do the comments in the configuration dump name?

Each row's source: # == <label> names the source a row came from, and , patched by <layers> is added when a later layer changed it. Together they show which layer put each row in place, and a patch that targets nothing is reported with its layer label.

What do the statuses in the schema dump mean?

Each declared entry gets a status: schema, partial, absent, unsupported or error. A partial entry states the limits of what could be read, and where an error is present the report marks itself incomplete. The dump never prints configuration values or the sources of expressions.