dotnet/runtime · error · RuntimeError

Tiering options have no effect for nativeaot collections.

Error message

Tiering options have no effect for nativeaot collections.

What it means

Thrown by SuperPMICollect.__init__() when the user requests a nativeaot collection mode (--nativeaot) and simultaneously passes --tiered_compilation or --tiered_pgo. NativeAOT is an ahead-of-time compilation scenario where tiered compilation and PGO have no meaning — the JIT runs once at build time via the IL compiler (ilc), not through the tiered runtime path.

Source

Thrown at src/coreclr/scripts/superpmi.py:723

        if coreclr_args.pmi:
            self.pmi_location = determine_pmi_location(coreclr_args)
            self.corerun = os.path.join(self.core_root, self.corerun_tool_name)

        if coreclr_args.crossgen2:
            self.corerun = os.path.join(self.core_root, self.corerun_tool_name)

        if coreclr_args.pmi or coreclr_args.crossgen2:
            self.assemblies = coreclr_args.assemblies
            self.exclude = coreclr_args.exclude
            if coreclr_args.tiered_compilation or coreclr_args.tiered_pgo:
               raise RuntimeError("Tiering options have no effect for pmi or crossgen2 collections.")

        if coreclr_args.nativeaot:
            self.ilc_rsps = coreclr_args.ilc_rsps
            self.exclude = coreclr_args.exclude
            if coreclr_args.tiered_compilation or coreclr_args.tiered_pgo:
                raise RuntimeError("Tiering options have no effect for nativeaot collections.")

        if coreclr_args.tiered_compilation and coreclr_args.tiered_pgo:
            raise RuntimeError("Pass only one tiering option.")

        self.coreclr_args = coreclr_args

        self.temp_location = None

        # Pathname for a temporary .MCL file used for noticing SuperPMI replay failures against base MCH.
        self.base_fail_mcl_file = None

        # The base .MCH file path
        self.base_mch_file = None

        # Final .MCH file path
        if self.coreclr_args.output_mch_path is not None:
            self.final_mch_file = os.path.abspath(self.coreclr_args.output_mch_path)
            final_mch_dir = os.path.dirname(self.final_mch_file)

View on GitHub (pinned to 290d5ab72c)

Solutions

Remove --tiered_compilation and --tiered_pgo flags when using --nativeaot with superpmi.py collect.
If you need tiered compilation behavior, use the default collection mode (a runtime collection command) or --pmi instead of --nativeaot.
Understand that NativeAOT compiles everything ahead-of-time via ilc; there is no tier-0/tier-1 distinction.

Example fix

# before: incompatible flags for nativeaot
python superpmi.py collect --nativeaot -ilc_rsps mylib.ilc.rsp --tiered_compilation

# after: remove tiering flags for nativeaot
python superpmi.py collect --nativeaot -ilc_rsps mylib.ilc.rsp

Defensive patterns

Strategy: validation

Validate before calling

# Validate argument compatibility before calling SuperPMICollect
if coreclr_args.nativeaot:
    if coreclr_args.tiered_compilation or coreclr_args.tiered_pgo:
        raise ValueError('Tiering options (--tiered_compilation, --tiered_pgo) are incompatible with --nativeaot')

Type guard

def is_valid_nativeaot_tiering_combo(nativeaot: bool, tiered_compilation: bool, tiered_pgo: bool) -> bool:
    if nativeaot:
        return not (tiered_compilation or tiered_pgo)
    return True

Try / catch

try:
    collector = SuperPMICollect(coreclr_args)
except RuntimeError as e:
    if 'Tiering options have no effect for nativeaot' in str(e):
        logging.error('Remove --tiered_compilation and --tiered_pgo when using --nativeaot')
        sys.exit(1)
    raise

Prevention

Never combine --tiered_compilation or --tiered_pgo with --nativeaot.
Understand that NativeAOT is ahead-of-time compilation with no runtime tiering.
If tiering investigation is needed, use the default collection command mode or --pmi instead of --nativeaot.

When it happens

Trigger: At lines 719-723: if coreclr_args.nativeaot and (coreclr_args.tiered_compilation or coreclr_args.tiered_pgo), line 723 raises. The combination is rejected because nativeaot collections invoke ilc with .rsp files, not the runtime JIT with tiering.

Common situations: A developer runs 'superpmi.py collect --nativeaot -ilc_rsps foo.ilc.rsp --tiered_compilation' not realizing NativeAOT is AOT-only. Copying tiering flags from a JIT investigation workflow into a NativeAOT collection command.

Related errors

AI-assisted analysis of dotnet/runtime@290d5ab72c (2026-08-06). Data as JSON: /api/errors/d41ec2492b8484b6. Report an issue: GitHub.