#3361·hydra

Show user frames in default instantiation error tracebacks

Author: omryCreated Aug 8, 2026Updated Sep 17, 2026

Problem

run_and_report() currently renders every CompactHydraException, including InstantiationException, as a message. For an instantiation failure in a Hydra task, that can hide the application line that called instantiate() and, when a user-provided target raises, the target's own frames. HYDRA_FULL_ERROR=1 shows those frames but also the Hydra implementation stack.

_call_target() already chains target failures with raise InstantiationException(...) from e. The default renderer should use that traceback and cause rather than discard them.

Scope for Hydra 1.4

Improve default rendering of instantiation errors only. Show a normal, concise Python traceback/exception chain that:

  • Retains the application call site of instantiate().
  • Retains user-provided target or constructor frames once execution enters that code.
  • Filters routine Hydra frames inside the instantiation implementation, without dropping user or plugin frames merely because they are part of the call chain.
  • Preserves the high-level InstantiationException message and configuration context such as full_key.
  • Shows an explicit cause (for example ImportError or an exception raised by the target) once. Account for the current wrapper message's repr(e) so the default output does not repeat the same cause text unnecessarily.
  • Falls back to the native traceback if safe filtering is not possible.

If failure occurs before the target is called, show the available application call site, Hydra error, and relevant cause; there are no target frames to preserve in that case. This is a rendering change for Hydra's application error path, not a change to the exception or traceback received by direct API callers.

Non-goals

  • Do not replace the message-oriented handling of all CompactHydraException subclasses with one generic traceback policy.
  • Do not add Python backtraces to command-line override errors; the invalid override and its explanation are the useful context there.
  • Do not change config-composition, missing-config, or search-path error rendering in this issue. Whether those messages carry enough config provenance is a separate investigation.
  • Do not introduce a new pretty-traceback format or remove the full native traceback option.

Acceptance criteria

  • An InstantiationException raised inside a Hydra task shows the application line that called instantiate() while routine Hydra instantiation frames are absent from default output.
  • If the target raises, its user-code frames and chained exception are visible; the cause is rendered once.
  • A target-location failure shows its chained cause and retains the Hydra error's full_key context.
  • Other compact error categories retain their existing behavior.
  • HYDRA_FULL_ERROR=1 and debugger detection continue to show the complete native traceback and chain.
  • Focused tests cover pre-target failure, failure inside a user target, chained causes, other compact categories, full-error mode, and debugger mode.
  • User and development documentation explains the filtered instantiation traceback and how to request the complete traceback.

Related work

  • #3329: Stop advertising HYDRA_FULL_ERROR=1 after routine errors.
  • #2590: Request to bypass Hydra exception formatting.
  • #1431: Compatibility with custom traceback renderers.