dotnet/runtime · error · RuntimeError

Error, toc file not created correctly at

Error message

Error, toc file not created correctly at: %s

What it means

Raised by SuperPMICollection.__create_toc__ after it invokes the 'mcs' tool (machine-code-source) with the -toc flag on the final MCH file. The function then checks for the existence of a Table-of-Contents file derived from the MCH path; if mcs did not produce it, the collection is considered corrupt or incomplete and the run aborts. The TOC is required for merge and replay operations to index method contexts inside the MCH.

Solutions

  1. Re-run mcs manually on the MCH file to see its stderr/exit code: '<mcs_path> -toc <final_mch_file>' and inspect any error output.
  2. Verify the MCH file is non-empty and not corrupt (check file size and, if possible, open with mcs -stat).
  3. Ensure the mcs binary matches the JIT-EE version and architecture of the collected MCH (use the mcs from the same build/Core_Root).
  4. Confirm write permission and free space in the directory that should contain toc_file.

Example fix

// before
command = [self.mcs_path, "-toc", self.final_mch_file]
run_and_log(command)
if not os.path.isfile(self.toc_file):
    raise RuntimeError("Error, toc file not created correctly at: %s" % self.toc_file)
// after
command = [self.mcs_path, "-toc", self.final_mch_file]
return_code = run_and_log(command)
if return_code != 0 or not os.path.isfile(self.toc_file):
    raise RuntimeError(f"mcs -toc failed (code {return_code}); toc file not created at: {self.toc_file}")
Defensive patterns

Strategy: validation

Validate before calling

import os, subprocess
def verify_toc_will_succeed(mcs_path, final_mch_file, toc_file):
    if not os.path.isfile(mcs_path):
        raise RuntimeError(f"mcs tool not found: {mcs_path}")
    if not os.path.isfile(final_mch_file) or os.path.getsize(final_mch_file) == 0:
        raise RuntimeError(f"MCH file missing or empty: {final_mch_file}")
    toc_dir = os.path.dirname(toc_file)
    if not os.path.isdir(toc_dir) or not os.access(toc_dir, os.W_OK):
        raise RuntimeError(f"TOC target directory missing or not writable: {toc_dir}")
    rc = subprocess.run([mcs_path, '-toc', final_mch_file]).returncode
    if rc != 0:
        raise RuntimeError(f"mcs -toc exited with code {rc}")

Try / catch

try:
    __create_toc__(self)
except RuntimeError as e:
    logging.error("TOC creation failed: %s", e)
    logging.error("Inspect MCH with: %s -stat %s", self.mcs_path, self.final_mch_file)
    raise

Prevention

When it happens

Trigger: Called during collection finalization: command = [self.mcs_path, '-toc', self.final_mch_file]; run_and_log(command) runs mcs, then os.path.isfile(self.toc_file) is False. Happens when mcs crashes or returns nonzero without writing the TOC, when the MCH file is zero-length or corrupt, when mcs_path points to the wrong binary, or when the TOC path derivation does not match what mcs actually writes.

Common situations: An mcs binary from a mismatched/incompatible runtime build; a corrupt or empty MCH file produced by a failed collection (e.g. the target process never JIT-compiled anything); running on a cross-arch target where the mcs binary cannot parse the native MCH; disk-full or permission denied on the spmi_location output directory.

Related errors

AI-assisted analysis of dotnet/runtime@60108ba66e (2026-08-10). Data as JSON: /api/errors/7d16f3d867b152a2. Report an issue: GitHub.

Appendix: source

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

        if not self.coreclr_args.skip_cleanup:
            if os.path.isfile(self.base_mch_file):
                os.remove(self.base_mch_file)
                self.base_mch_file = None

    def __create_toc__(self):
        """ Create a TOC file

        Notes:
            <mcl> -toc <s_finalMchFile>
        """

        logging.info("Creating TOC file")

        command = [self.mcs_path, "-toc", self.final_mch_file]
        run_and_log(command)

        if not os.path.isfile(self.toc_file):
            raise RuntimeError("Error, toc file not created correctly at: %s" % self.toc_file)

    def __verify_final_mch__(self):
        """ Verify the resulting MCH file is error-free when running SuperPMI against it with the same JIT used for collection.

        Notes:
            <SuperPmiPath> -p -f <s_finalFailMclFile> <s_finalMchFile> <jitPath>
        """

        logging.info("Verifying MCH file")

        mch_files = [ self.final_mch_file ]
        spmi_replay = SuperPMIReplay(self.coreclr_args, mch_files, self.jit_path)
        passed = spmi_replay.replay()

        if not passed:
            raise RuntimeError("Error, unclean replay.")

    def __process_for_ci__(self):

View on GitHub (pinned to 60108ba66e)