Merge pull request #162 from modern-python/153-docs-improve-error-on-provider-type-duplication

add instruction about duplicate provider error

Author: lesnik512

docs/troubleshooting/duplicate-type-error.md

@@ -0,0 +1,70 @@
+# Duplicate Type Error
+
+This error occurs when two or more providers are registered with the same `bound_type`. Modern-DI uses the `bound_type` to resolve dependencies by type, so each type must be unique in the providers registry.
+
+## Understanding the Error
+
+When you see this error:
+
+```
+RuntimeError: Provider is duplicated by type <class 'SomeType'>.
+```
+
+It means you have multiple providers that can provide the same type. This typically happens when:
+
+1. You have multiple factories that return the same type
+2. You're using the same class in different contexts with different configurations
+
+## How to Resolve
+
+To fix this error, you need to:
+
+1. Set `bound_type=None` on one of the duplicate providers to make it unresolvable by type
+2. Explicitly pass dependencies via the `kwargs` parameter to avoid automatic resolution
+
+Here's a complete example showing both steps:
+
+```python
+from modern_di import Group, Scope, providers
+
+
+class DatabaseConfig:
+    def __init__(self, connection_string: str) -> None:
+        self.connection_string = connection_string
+
+
+class Repository:
+    def __init__(self, db_config: DatabaseConfig) -> None:
+        self.db_config = db_config
+
+
+class MyGroup(Group):
+    # Step 1: Set bound_type=None on the secondary provider or for both providers
+    # This provider can be resolved by type: container.resolve(DatabaseConfig)
+    primary_db_config = providers.Factory(
+        scope=Scope.APP,
+        creator=DatabaseConfig,
+        kwargs={"connection_string": "postgresql://primary"}
+    )
+
+    # This provider cannot be resolved by type
+    # Must use: container.resolve_provider(MyGroup.secondary_db_config)
+    secondary_db_config = providers.Factory(
+        scope=Scope.APP,
+        creator=DatabaseConfig,
+        bound_type=None,  # <-- Step 1: Makes it unresolvable by type
+        kwargs={"connection_string": "postgresql://secondary"}
+    )
+
+    # Step 2: Explicitly pass dependencies via kwargs for second repository or for both
+    primary_repository = providers.Factory(
+        scope=Scope.APP,
+        creator=Repository,  # <-- Implicit dependency, no kwargs
+    )
+
+    secondary_repository = providers.Factory(
+        scope=Scope.APP,
+        creator=Repository,
+        kwargs={"db_config": secondary_db_config}  # <-- Step 2: Explicit dependency
+    )
+```

mkdocs.yml

@@ -17,6 +17,8 @@ nav:
       - Litestar: integrations/litestar.md
   - Testing:
       - Fixtures: testing/fixtures.md
+  - Troubleshooting:
+      - Duplicate Type Error: troubleshooting/duplicate-type-error.md
   - Migration:
       - To 1.x: migration/to-1.x.md
       - To 2.x: migration/to-2.x.md

modern_di/errors.py

@@ -11,4 +11,10 @@
 FACTORY_ARGUMENT_RESOLUTION_ERROR = (
     "Argument {arg_name} of type {arg_type} cannot be resolved. Trying to build dependency {bound_type}."
 )
-PROVIDER_DUPLICATE_TYPE_ERROR = "Provider is duplicated by type {provider_type}"
+PROVIDER_DUPLICATE_TYPE_ERROR = (
+    "Provider is duplicated by type {provider_type}. "
+    "To resolve this issue:\n"
+    "1. Set bound_type=None on one of the providers to make it unresolvable by type\n"
+    "2. Explicitly pass dependencies via the kwargs parameter to avoid automatic resolution\n"
+    "See https://modern-di.readthedocs.io/latest/troubleshooting/duplicate-type-error/ for more details"
+)

tests/registries/test_providers_registry.py

@@ -16,6 +16,6 @@ def test_providers_registry_add_provider_duplicates() -> None:
     providers_registry.add_providers(str_factory)
 
     with (
-        pytest.raises(RuntimeError, match="Provider is duplicated by type"),
+        pytest.raises(RuntimeError, match="Provider is duplicated by type <class 'str'>"),
     ):
         providers_registry.add_providers(str_factory)