DSH plugin: profile reload requires the root Include entry

dsh: profile reload requires the root Include entry means a DeepSeek Harness profile reload could not find the root Include entry: a reload must begin from the root Include — the profile's cordis.yml — to recompose the plugin tree, and without it the whole tree fails to build and the operation returns failed. Error X → do W: restore the root Include entry, then start a fresh instance, rather than repeatedly firing the plugin start/stop toggle on the instance that is already throwing that error (source).

The message reads like a broken config, but it is really "a reload precondition was not met". A user hit this in the wild: inside a CLI web instance they called the official pluginManager.setBundleEnabled to hot-toggle a bundle, the call returned application:"failed", and it came with this exact sentence; by then the on-disk config had already changed while the process was still alive (source). The three things below — what it is, how to fix it, and why it fires — answer that scene in order, and two official mechanics follow.

What the profile reload requires the root Include entry error means

The root Include entry is the DeepSeek Harness loader entry that loads a profile's root config, and it points at the profile's cordis.yml; a profile reload has to start from that root Include to layer user patches and bundles one on top of another (source). Line up the three actors first:

Read it in this order:

1. It is a reload precondition, not data corruption — the message (dsh: profile reload requires the root include entry, commonly typed lowercase when searching) says "a reload needs the root Include entry", a failed precondition check, not that your session or model config was written badly. Expected: the file is most likely still on disk; this one reload just did not get it.
2. It shows up more on the "live instance reload" path — a process starting from zero (a cold boot) also reads the root Include, but it goes through the boot path; a hot reload goes through "recompose the plugin tree", which is stricter about the root Include being ready. Expected: the same config comes up fine after a process restart, which is the signature of this error.
3. It is not the same as "a plugin is not enabled" — a disabled plugin is one entry switched off with disabled: true while the tree still composes; this error is the footing not being found, so the whole tree cannot compose. Expected: when it fires, usually nothing takes effect, rather than only one plugin being off.

Keep one sentence: this is a footing error that says "the reload cannot proceed", not a fault in any single plugin.

Two neighbouring errors are easy to confuse with this one. A "plugin tree failed to load" message points at an entry inside the tree — a bundle or plugin failed to apply — and it can appear even when the root Include is healthy; this error is the footing itself, so it fires before any individual entry is judged. And "overlay must be a top-level YAML array of loader patch entries" is about the patch file cordis.patch.yml, not the root file — the same YAML family, a different file — so read the path in the message before assuming it is the root config. Reading the path and the phrase together is what tells the three apart in seconds.

How to fix profile reload requires the root Include entry: restore the root and restart

The main line of the fix is "put the root Include entry back, then restart the instance" — because a live instance composes its plugin list at boot, a runtime hot reload is stricter about the root Include, and one restart is the least trouble. Run the steps in order:

1. First confirm the root Include entry is there. Open the profile directory and find the root config cordis.yml (a path shaped like $DSH_HOME/profiles/<name>/cordis.yml). Expected: the file exists and its content is a top-level array ([...]); if it is empty or not an array, this is where the problem is.
2. Restore the root config content to its default. If cordis.yml was emptied or written as a non-array, restore it to a top-level array of entries per the official config catalog — the root config is fixed content and plugins should not be written into it (source). Expected: after saving, the file is a valid YAML top-level array.
3. Check whether a plugin wrote config into the root file. Some plugins write the composed rows back into cordis.yml; the correct behaviour is to write into the patch layer (cordis.patch.yml), not the root file. Expected: the root file keeps its fixed content and the plugin entries all land in the patch layer.
4. Restart the instance instead of hot-reloading. Stop dsh web with Ctrl+C, then run npx @deepseek-ai/dsh web again. Expected: the terminal prints the listening address again, the plugin tree recomposes from the root Include, and this error no longer appears (source).
5. Confirm the compose result with dump. Run dsh --profile web --dump-config and check whether the plugin entry you care about shows up in the composed result (source). Expected: the entry is present and its content is right, meaning the root Include and the patch layer line up.

A useful confirmation detail: --dump-config prints the composed result, so if your entry is missing there but present in the patch file, the problem is a layering or ordering mistake rather than a missing root Include; --dump-config-schema instead prints which keys are valid, which is the one to reach for when you are rewriting the root config and want to avoid writing another illegal shape. Running the two together separates "the footing is missing" from "the footing is fine but a layer wrote the wrong thing".

One reminder: do not keep firing the plugin start/stop toggle on the instance that is throwing — that is precisely the action that triggers this sentence, and the more you toggle the messier it gets; edit the file and restart is the right road.

Why profile reload requires the root Include entry happens: hand-edited YAML and bundle toggles

The two high-frequency scenes are "hand-editing cordis.yml" and "toggling bundles on a live instance" — the first turns the content the root Include points at into an illegal shape, and the second triggers a reload with no ready root Include. Compare them:

Row by row:

1. Editing the root file is the easiest trap: cordis.yml is the root config with a fixed shape; pushing plugin entries into it can be judged illegal on the next reload. Expected: the error disappears once the plugin entries are moved to cordis.patch.yml.
2. When a plugin overwrites config, look at which layer it writes to: if a plugin rewrites config on your behalf and lands on the root file, disable or uninstall it first from the DSH Plugin Hub installed list, then restore the root config by hand. Expected: after disabling it in the market and restarting, the root file is no longer rewritten.
3. The bundle start/stop path is itself a hot reload: the official setBundleEnabled triggers one reload when called on a live instance, and that instance's bundle list was fixed at boot, so it is more likely to hit the root Include precondition check (source). Expected: switching to "edit config + restart" stops this sentence from appearing.
4. Config layering and overwrite order are a different thing: which layer overrides which, and why --patch has the highest priority, is config-layering knowledge, not this reload error; it is written up in DeepSeek Harness plugin config: config blocks and patch overrides. Expected: you can tell "the footing is missing" apart from "the layers were written wrong".

Boundary: if what you hit is "a validation failure that happens intermittently during concurrent launches, with the file intact afterwards", that is a cordis.yml overwrite race, not this error — the race is covered in DSH plugin concurrent launches corrupt the profile.

The misjudgment to avoid is blaming a plugin for a config-shape problem. If you enabled a bundle from the market switch and then saw this error, it is tempting to uninstall that plugin, but the plugin is usually fine — the switch called the runtime start/stop path that needs a ready root Include. Check the root file's shape and restart before you remove anything, because uninstalling a healthy plugin only removes the evidence that pointed you at the reload path.

Troubleshooting notes for a DSH plugin profile reload

1. First tell "cold boot works, hot reload errors" apart — that is the signature of this error, so do not suspect data corruption first.
2. Do not use the root file as scratch paper — plugin entries belong in the patch layer; root cordis.yml holds only fixed content.
3. Restart once you have edited — the bundle list is composed at boot, and a runtime hot reload is pickier about preconditions than a cold boot.
4. Verify with dump — --dump-config shows the composed result, --dump-config-schema shows what can be configured.
5. Trace a plugin that rewrites config — if you suspect a plugin touched the root file, disable it in the market first, then restore the root config.

The official DSH plugin mechanism behind a profile reload

Understand two official statements and troubleshooting gains direction: a profile's root config is loaded by the loader's include entry, so a plugin-tree reload has to get that root Include back; and a bundle list is composed at boot. Two points:

1. The root Include is the load entry point — the official docs take "every config: block can be set by a cordis.yml entry" as the general principle, and this root config is loaded through the loader's include entry (source). Expected: once you grasp "include is the entry point", you see why the whole tree cannot compose when it is missing.
2. Hot reload and cold boot are split — a patch change goes through a profile reload, while the bundle list is composed at boot, so relying on runtime start/stop is often less reliable than a restart (source). Expected: treating "edit file + restart" as the default move avoids most errors in this family.

Rather than editing cordis.yml by hand and worrying you will wipe the root Include entry, drive plugin start/stop and uninstall from the DSH Plugin Hub GUI — it hands the syntax to standard commands and leaves you with just the confirm click. Get it at https://dsh-plugin.org/.

Sources: dsh CLI README, plugin config catalog (official docs), community plugin dsh-backroom field report.