Container Validation

Container Validation

Validate your dependency graph during compile time to catch wiring errors early.

The container can validate service wiring before runtime to detect dependency graph issues early.

Programmatic usage

const result = await container.compile({
  validate: true,
  throwOnError: false
})

console.log(result.isValid)
console.log(result.errors)
console.log(result.warnings)
console.log(result.info)

By default, when validate: true and throwOnError is not false, compile throws ContainerValidationError if validation errors exist.

await container.compile({ validate: true })

Validation checks

Errors

• Missing dependency
• Circular dependency
• Unresolved parameters (%param%)
• Invalid alias (invalid_alias) when an alias points directly to an unregistered service
• Multiple keyed defaults (keyed_group_multiple_defaults)

Warnings

• Unused nullable references (@?service) when target always exists
• Deprecated service used by non-deprecated services

Info

• Tagged services without any tag consumer

CLI usage

ndi container:validate [options] <path>

Options:

• --format <format>: text or json
• --strict: exit with code 1 when warnings are present

Examples:

ndi container:validate ./config/services.yaml
ndi container:validate --format=json ./config/services.yaml
ndi container:validate --strict ./config/services.yaml

Notes

• Without validate: true, compile behaves as before.
• With throwOnError: false, compile returns the full validation report instead of throwing.
• Validation runs before and after compilation, so aliases added or invalidated by compiler passes are checked against the compiled graph as well.
• Alias validation follows runtime lookup semantics: an alias is checked against its direct target, and an alias-to-alias target must itself be a registered service id.
• Without validation, an unused invalid alias is not proactively rejected and fails naturally when requested.