nodejs/node · error · NotImplementedError

Unknown debug format

Error message

Unknown debug format %s

What it means

Raised by XcodeSettings._GetDebuggingFlags when DEBUG_INFORMATION_FORMAT is set to a value that is none of 'dwarf', 'stabs', or 'dwarf-with-dsym'. The error message interpolates the unrecognized value so you can identify the offending setting. This protects against silent miscompilation by failing fast on an unknown debug format.

Solutions

1. Correct the DEBUG_INFORMATION_FORMAT value to one of: 'dwarf', 'dwarf-with-dsym', or 'stabs'.
2. Check for case sensitivity — use exactly lowercase 'dwarf'.
3. Remove the key to fall back to the 'dwarf' default.
4. Upgrade the gyp checkout if you believe the value is a legitimately new Xcode format.

Example fix

# before
'DEBUG_INFORMATION_FORMAT': 'DWARFF',
# after
'DEBUG_INFORMATION_FORMAT': 'dwarf',

# Validate DEBUG_INFORMATION_FORMAT before gyp generation
_VALID = {'dwarf', 'dwarf-with-dsym', 'stabs'}
fmt = config.get('DEBUG_INFORMATION_FORMAT', 'dwarf')
if fmt not in _VALID:
    raise ValueError(f'DEBUG_INFORMATION_FORMAT must be one of {_VALID}, got {fmt!r}')

When it happens

Trigger: A target's xcode_settings dict has DEBUG_INFORMATION_FORMAT set to a typo or a value not in the handled set — for example 'DWARF' (wrong case), 'dwarf2', 'none', or any arbitrary string. The final else branch in the debug-format chain raises.

Common situations: Typo in the format string. Copy-pasting a newer Xcode build setting value not yet understood by this gyp version. Case mismatch (Xcode build settings are usually lowercase here).

Related errors

• stabs debug format is not supported yet.
• Xcode environment variables are cyclically dependent
• Error running
• Found multiple children with path
• Multiple toolsets not supported in xcode build

AI-assisted analysis of nodejs/node@1b2de5e052 (2026-08-13). Data as JSON: /api/errors/b82d2ad5fec0dc5b. Report an issue: GitHub.

Appendix: source

Thrown at tools/gyp/pylib/gyp/xcode_emulation.py:617

            # TODO: In this case, it depends on the target. xcode passes
            # mdynamic-no-pic by default for executable and possibly static lib
            # according to mento

        if self._Test("GCC_ENABLE_PASCAL_STRINGS", "YES", default="YES"):
            cflags.append("-mpascal-strings")

        self._Appendf(cflags, "GCC_OPTIMIZATION_LEVEL", "-O%s", default="s")

        if self._Test("GCC_GENERATE_DEBUGGING_SYMBOLS", "YES", default="YES"):
            dbg_format = self._Settings().get("DEBUG_INFORMATION_FORMAT", "dwarf")
            if dbg_format == "dwarf":
                cflags.append("-gdwarf-2")
            elif dbg_format == "stabs":
                raise NotImplementedError("stabs debug format is not supported yet.")
            elif dbg_format == "dwarf-with-dsym":
                cflags.append("-gdwarf-2")
            else:
                raise NotImplementedError("Unknown debug format %s" % dbg_format)

        if self._Settings().get("GCC_STRICT_ALIASING") == "YES":
            cflags.append("-fstrict-aliasing")
        elif self._Settings().get("GCC_STRICT_ALIASING") == "NO":
            cflags.append("-fno-strict-aliasing")

        if self._Test("GCC_SYMBOLS_PRIVATE_EXTERN", "YES", default="NO"):
            cflags.append("-fvisibility=hidden")

        if self._Test("GCC_TREAT_WARNINGS_AS_ERRORS", "YES", default="NO"):
            cflags.append("-Werror")

        if self._Test("GCC_WARN_ABOUT_MISSING_NEWLINE", "YES", default="NO"):
            cflags.append("-Wnewline-eof")

        # In Xcode, this is only activated when GCC_COMPILER_VERSION is clang or
        # llvm-gcc. It also requires a fairly recent libtool, and
        # if the system clang isn't used, DYLD_LIBRARY_PATH needs to contain the

View on GitHub (pinned to 1b2de5e052)