Diagnose null assertions and premature late reads

Understand the likely causes

• Candidates include an absent map key, a present null, a wrong external field type, a required value that was never validated, or an object exposed before its initialization protocol completed. A non-null type can still contain a blank or otherwise invalid string. Separate presence, content validity, and lifecycle readiness instead of treating them as one guarantee.

Locate the exact assumption that failed

Record the failing operation and trace its value back to the input or initializer. Was ! added after a map lookup, or was late used to avoid supplying required constructor data? For a nullable map value, use the source contract to distinguish a missing key from a present null when that matters. Do not copy real payloads, tokens, or personal data into the investigation. Preserve the field name, expected type, and a synthetic reproduction. The goal is to identify the first unsupported promise rather than merely the last access where it becomes visible.

field: batchCode
source: decoded external map
required_checks: [present, string, nonblank, permitted_format]
separate_checks: [caller_authorization, current_resource_state]
unsafe_shortcut: assert presence with ! before validation

Choose a correction for the actual failure category

An optional display note may legitimately use a documented fallback. A required batch identity should normally produce a validation failure when absent, rather than an invented identifier. A late field needs an owner and a guaranteed initialization order, or replacement with construction-time data. If setup is asynchronous, do not expose the ready interface before its completion unless the type explicitly models a pending state. Adding ! cannot wait for setup, and late does not validate the resulting value. Keep a distinct failure path when an internal invariant is actually violated.

Normalize one boundary into an explicit local result

The pure helper below accepts unknown input and returns a nonblank trimmed code or null. It demonstrates a narrow presence and type policy only; it does not implement the permitted identifier grammar, resource lookup, or authorization. The fixed cases distinguish missing data, a wrong type, and a usable string. If callers need different reasons, replace the shared null result with a typed rejection model. Avoid converting all cases into a successful empty value because that shifts the defect into later storage, routing, or UI behavior.

String? requiredCode(Object? value) {
  if (value is! String) return null;
  final normalized = value.trim();
  return normalized.isEmpty ? null : normalized;
}
void main() {
  for (final value in <Object?>[null, 7, ' B-8 ']) {
    print(requiredCode(value) ?? 'invalid code');
  }
}

invalid code
invalid code
B-8

Reproduce the original lifecycle path, not only a happy case

In a compatible isolated project, test missing, null, blank, wrong-type, valid, and malformed-format input as required by the contract. For late state, exercise the read-before-ready path and every initialization failure or cancellation path. Verify that callers receive an explicit invalid or pending result rather than a false success, and that logs contain only safe context. If a local snapshot resolves a promotion issue, confirm snapshot semantics are actually intended. This guide supplies a proposed validation plan; it does not record a Dart analyzer, runtime, asynchronous ordering, or UI test pass.

Keep it from recurring

• Review ! additions, late declarations, external decoding, and object exposure points together. Require validated construction for essential state where practical, keep optional display defaults separate from domain identities, and document any pending initialization state. Never report a reasoned output as an executed test.