# error: Multiple top-level packages discovered in a flat-layout: ['src', 'tests', 'docs'].

- **ID:** `python/setuptools-package-discovery-flat-layout`
- **Domain:** python
- **Category:** config_error
- **Verification:** ai_generated
- **Fix Rate:** 80%

## Root Cause

setuptools auto-discovery refuses to guess which top-level directory is the real package when several sibling directories look like packages; explicit configuration is required.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| 3.x | active | — | — |

## Workarounds

1. **** (97% success)
   ```
   [tool.setuptools.packages.find]
where = ["src"]
include = ["mypkg*"]
# or list them
[tool.setuptools]
packages = ["mypkg"]
   ```
2. **** (94% success)
   ```
   mkdir -p src/mypkg
mv mypkg/* src/mypkg/
touch src/mypkg/__init__.py
# then configure
[tool.setuptools.packages.find]
where = ["src"]
   ```

## Dead Ends

- **** — Works around the symptom but breaks conventional tooling and CI that expect those names. (60% fail)
- **** — Makes the ambiguity worse; setuptools now sees even more candidate packages. (80% fail)