fix: warn when running inside a nested project, for #8321 by stasadev · Pull Request #8327 · ddev/ddev

stasadev · 2026-04-16T18:17:40Z

The Issue

Fixes Nested .ddev folders should provide more explicit warnings #8321

When a user runs ddev from inside a directory that has a parent project, the command silently used whichever project was found first walking up the tree, with no indication a nested project structure was detected. The most common symptom: a user has a custom command defined in the parent project, runs it from a subdirectory that is itself a DDEV project, and sees a cryptic "unknown command" error with no explanation.

How This PR Solves The Issue

A new DetectNestedProject() function in pkg/ddevapp/utils.go walks up from the current directory and returns the child and parent project roots when two .ddev/config.yaml files are found in an ancestor relationship.

The warning is emitted in Execute() in cmd/ddev/cmd/root.go - after Cobra runs - so it fires for every invocation including unknown commands (Cobra skips all hooks for those, so placing it in PersistentPreRun would miss the most common case). The warning is suppressed for --json-output and shell-completion invocations.

ddev describe -j gains a .raw.parent_approot field when run from a nested project. This is intended for IDE integrations such as DDEV Integration (JetBrains) and DDEV Manager (VS Code): if parent_approot is present, the integration knows it is looking at a nested project and can act accordingly - for example, by not auto-starting project containers.

Manual Testing Instructions

In a DDEV project directory, ddev config --auto && ddev start
git clone https://github.com/matomo-org/matomo
cd matomo && ddev describe - a nested project warning should appear after the output
cd matomo && ddev some-custom-command-from-parent - warning should appear alongside the "unknown command" error, explaining why the command is missing
cd matomo && ddev describe -j | jq -r .raw.parent_approot - should print the parent project root path
From the parent directory: ddev describe -j | jq -r .raw.parent_approot - should print null

Automated Testing Overview

New TestDetectNestedProject and TestCheckForConf in pkg/ddevapp/utils_test.go
New TestNestedProjectWarning in cmd/ddev/cmd/root_test.go

Release/Deployment Notes

The warning fires on every command when a nested project is detected. This is intentional for now - we want to be noisy so users notice the situation, and we can gather feedback before deciding on a more permanent solution (e.g. a config option to suppress the warning).

Nested DDEV projects are unusual because they are confusing, but they do occur in real workflows - a notable example is Drupal core development, where contrib modules may each have their own .ddev/config.yaml. This PR does not change how DDEV resolves which project to use in that situation; it only makes the ambiguity visible. Further changes will be driven by community feedback.

github-actions · 2026-04-16T18:23:42Z

Download the artifacts for this pull request:

See Testing a PR.

tyler36

Works as intended.

I wonder if the warning would be better at the bottom of the table?
While testing in a VSCode terminal (a paneled terminal inside the main app), I had to scroll up to see the warning. Placing the warning last would make it more visible.

Tests

$ ddev -v
ddev version v1.25.1-80-g952d03d9b

ddev config --auto && ddev start
$ cd matomo && ddev describe
Nested project at "/home/user47/tmp/ddev-8327/matomo" overrides parent at "/home/user47/tmp/ddev-8327"
If this is not intended, run the command from the parent project root directory.
...

stasadev · 2026-04-20T12:15:18Z

I wonder if the warning would be better at the bottom of the table?

Good idea, but it depends on the command - for ddev config / ddev start, it's better to show it earlier.

Maybe we should add global pre/post-run checks for this instead, since having projects inside projects is quite unusual.

tyler36 · 2026-04-20T13:30:17Z

Maybe we should add global pre/post-run checks for this instead, since having projects inside projects is quite unusual.

I like it.
It's unusual, but I've tripped over this a few times over the years. I appreciate DDEV can nudge me in the right direction at 3am in the monrning. :)

stasadev · 2026-04-20T15:54:57Z

The logic has been updated, see the changes in the first post.

tyler36 · 2026-04-20T23:00:09Z

Confirming DDEV now prints warning after table.

$ ddev describe
...
├──────────────┼─────────┼──────────────────────────────────────────────────┼────────────────────┤
│ Project URLs │         │ https://lara12-base-demo.ddev.site,              │                    │
│              │         │ http://lara12-base-demo.ddev.site                │                    │
└──────────────┴─────────┴──────────────────────────────────────────────────┴────────────────────┘

Nested project at "/home/user47/tmp/ddev-8327/lara12-base-demo" overrides parent at "/home/user47/tmp/ddev-8327"
If this is not intended, run the command from the parent project root directory.

$

ddev -v also displays a warning.

$  ddev -v
ddev version v1.25.1-91-gdf3a20709
Nested project at "/home/user47/tmp/ddev-8327/lara12-base-demo" overrides parent at "/home/user47/tmp/ddev-8327"
If this is not intended, run the command from the parent project root directory.

## The Issue - Fixes ddev#8321 When a user runs `ddev` from inside a directory that has a parent project, the command silently used whichever project was found first walking up the tree, with no indication a nested project structure was detected. ## How This PR Solves The Issue `CheckForConf` now detects when a nested `.ddev/config.yaml` is found inside a directory that already belongs to a parent project. It emits a one-time warning naming both paths and returns the nested (inner) project. ## Manual Testing Instructions 1. `ddev config --auto && ddev start` 2. `git clone https://github.com/matomo-org/matomo` 3. `cd matomo && ddev describe` — a nested project warning should appear ## Automated Testing Overview `TestCheckForConf` in `pkg/ddevapp/utils_test.go` covers: - No config found: error returned - Config only in parent: parent path returned, no warning - Config in both parent and child: child path returned with warning ## Release/Deployment Notes Minor UX improvement, no breaking changes. Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

## The Issue - Fixes ddev#8321 When a user runs `ddev` from inside a directory that has a parent project, the command silently used whichever project was found first walking up the tree, with no indication a nested project structure was detected. The most common symptom: a user has a custom command defined in the parent project, runs it from a subdirectory that is itself a DDEV project, and sees a cryptic "unknown command" error with no explanation. ## How This PR Solves The Issue A new `DetectNestedProject()` function in `pkg/ddevapp/utils.go` walks up from the current directory and returns the child and parent project roots when two `.ddev/config.yaml` files are found in an ancestor relationship. The warning is emitted in `Execute()` in `cmd/ddev/cmd/root.go` - after Cobra runs - so it fires for every invocation including unknown commands (Cobra skips all hooks for those, so placing it in `PersistentPreRun` would miss the most common case). The warning is suppressed for `--json-output` and shell-completion invocations. `ddev describe -j` gains a `parent_approot` field when run from a nested project. This is intended for IDE integrations such as [DDEV Integration](https://github.com/ddev/ddev-intellij-plugin) (JetBrains) and [DDEV Manager](https://github.com/ddev/vscode-ddev-manager) (VS Code): if `parent_approot` is present, the integration knows it is looking at a nested project and can act accordingly - for example, by not auto-starting project containers. ## Manual Testing Instructions 1. In a DDEV project directory, `ddev config --auto && ddev start` 2. `git clone https://github.com/matomo-org/matomo` 3. `cd matomo && ddev describe` - a nested project warning should appear after the output 4. `cd matomo && ddev some-custom-command-from-parent` - warning should appear alongside the "unknown command" error, explaining why the command is missing 5. `cd matomo && ddev describe -j | jq -r .raw.parent_approot` - should print the parent project root path 6. From the parent directory: `ddev describe -j | jq -r .raw.parent_approot` - should print `null` ## Automated Testing Overview New `TestDetectNestedProject` and `TestCheckForConf` in `pkg/ddevapp/utils_test.go` New `TestNestedProjectWarning` in `cmd/ddev/cmd/root_test.go` ## Release/Deployment Notes Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

rfay · 2026-04-21T03:50:15Z

Rebased just to get green build hopefully, now that wsl2 fix is green. Hopefully I can review tomorrow.

rfay · 2026-04-21T13:03:20Z

This solves the unintended shell/custom command problem, but doesn't solve the ddev start problem at all, which I think was part of #8321

rfay@rfay-mba-m4:~/workspace/d11/web/modules/matomo$ ddev start
Starting matomo...
[+] pull 18/21
 ⠦ Image ddev/ddev-dbserver-mysql-5.7:v1.25.2 [⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡀⣿⠀⣿⣿] 19.92MB / 163.8MB Pulling                          4.6s

rfay

Thanks for doing this, which solves a part of the problem, but I don't think it solves enough of it to go into v1.25.2 yet. We may want to think about expanding the scope a bit , either choosing to use the parent project, or providing some kind of config to sort this out. Or at least providing guidance to add-ons and others that try this kind of thing.

It's so ugly that ddev describe shows the nested project before showing the warning, and so ugly that ddev start tries to start the nested project. ddev snapshot tries to start and take a snapshot of the child.

stasadev · 2026-04-21T13:52:58Z

This solves the unintended shell/custom command problem, but doesn't solve the ddev start problem at all

The warning is easy to move and show before the command.

stasadev requested a review from a team as a code owner April 16, 2026 18:17

github-actions Bot added the bugfix label Apr 16, 2026

stasadev mentioned this pull request Apr 16, 2026

Nested .ddev folders should provide more explicit warnings #8321

Open

4 tasks

tyler36 approved these changes Apr 18, 2026

View reviewed changes

stasadev force-pushed the 20260416_stasadev_nested_config branch from 952d03d to df3a207 Compare April 20, 2026 15:52

stasadev requested a review from rfay April 20, 2026 15:59

stasadev and others added 2 commits April 20, 2026 21:49

rfay force-pushed the 20260416_stasadev_nested_config branch from df3a207 to ac47039 Compare April 21, 2026 03:49

rfay changed the title ~~fix: warn when running inside a nested project, fixes #8321~~ fix: warn when running inside a nested project, for #8321 Apr 21, 2026

rfay requested changes Apr 21, 2026

View reviewed changes

stasadev marked this pull request as draft April 21, 2026 14:37

rfay added this to the v1.25.3 milestone Apr 22, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: warn when running inside a nested project, for #8321#8327

fix: warn when running inside a nested project, for #8321#8327
stasadev wants to merge 2 commits into
ddev:mainfrom
stasadev:20260416_stasadev_nested_config

stasadev commented Apr 16, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 16, 2026 •

edited

Loading

Uh oh!

tyler36 left a comment

Uh oh!

stasadev commented Apr 20, 2026

Uh oh!

tyler36 commented Apr 20, 2026

Uh oh!

stasadev commented Apr 20, 2026

Uh oh!

tyler36 commented Apr 20, 2026

Uh oh!

rfay commented Apr 21, 2026

Uh oh!

rfay commented Apr 21, 2026

Uh oh!

rfay left a comment

Uh oh!

stasadev commented Apr 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

stasadev commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

The Issue

How This PR Solves The Issue

Manual Testing Instructions

Automated Testing Overview

Release/Deployment Notes

Uh oh!

github-actions Bot commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tyler36 left a comment

Choose a reason for hiding this comment

Tests

Uh oh!

stasadev commented Apr 20, 2026

Uh oh!

tyler36 commented Apr 20, 2026

Uh oh!

stasadev commented Apr 20, 2026

Uh oh!

tyler36 commented Apr 20, 2026

Uh oh!

rfay commented Apr 21, 2026

Uh oh!

rfay commented Apr 21, 2026

Uh oh!

rfay left a comment

Choose a reason for hiding this comment

Uh oh!

stasadev commented Apr 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

stasadev commented Apr 16, 2026 •

edited

Loading

github-actions Bot commented Apr 16, 2026 •

edited

Loading