JSON Output

This chapter documents the JSON structures emitted by rustc. JSON may beenabled with the —error-format=json flag. Additionaloptions may be specified with the —json flag which canchange which messages are generated, and the format of the messages.

JSON messages are emitted one per line to stderr.

If parsing the output with Rust, thecargo_metadata crate providessome support for parsing the messages.

When parsing, care should be taken to be forwards-compatible with future changesto the format. Optional values may be null. New fields may be added. Enumeratedfields like "level" or "suggestion_applicability" may add new values.

Diagnostics

Diagnostic messages provide errors or possible concerns generated duringcompilation. rustc provides detailed information about where the diagnosticoriginates, along with hints and suggestions.

Diagnostics are arranged in a parent/child relationship where the parentdiagnostic value is the core of the diagnostic, and the attached childrenprovide additional context, help, and information.

Diagnostics have the following format:

  1. {
  2.     /* The primary message. */
  3.     "message": "unused variable: `x`",
  4.     /* The diagnostic code.
  5.        Some messages may set this value to null.
  6.     */
  7.     "code": {
  8.         /* A unique string identifying which diagnostic triggered. */
  9.         "code": "unused_variables",
  10.         /* An optional string explaining more detail about the diagnostic code. */
  11.         "explanation": null
  12.     },
  13.     /* The severity of the diagnostic.
  14.        Values may be:
  15.        - "error": A fatal error that prevents compilation.
  16.        - "warning": A possible error or concern.
  17.        - "note": Additional information or context about the diagnostic.
  18.        - "help": A suggestion on how to resolve the diagnostic.
  19.        - "failure-note": A note attached to the message for further information.
  20.        - "error: internal compiler error": Indicates a bug within the compiler.
  21.     */
  22.     "level": "warning",
  23.     /* An array of source code locations to point out specific details about
  24.        where the diagnostic originates from. This may be empty, for example
  25.        for some global messages, or child messages attached to a parent.
  27.        Character offsets are offsets of Unicode Scalar Values.
  28.     */
  29.     "spans": [
  30.         {
  31.             /* The file where the span is located.
  32.                For spans located within a macro expansion, this will be the
  33.                name of the expanded macro in the format "<MACRONAME macros>".
  34.             */
  35.             "file_name": "lib.rs",
  36.             /* The byte offset where the span starts (0-based, inclusive). */
  37.             "byte_start": 21,
  38.             /* The byte offset where the span ends (0-based, exclusive). */
  39.             "byte_end": 22,
  40.             /* The first line number of the span (1-based, inclusive). */
  41.             "line_start": 2,
  42.             /* The last line number of the span (1-based, inclusive). */
  43.             "line_end": 2,
  44.             /* The first character offset of the line_start (1-based, inclusive). */
  45.             "column_start": 9,
  46.             /* The last character offset of the line_end (1-based, exclusive). */
  47.             "column_end": 10,
  48.             /* Whether or not this is the "primary" span.
  50.                This indicates that this span is the focal point of the
  51.                diagnostic.
  53.                There are rare cases where multiple spans may be marked as
  54.                primary. For example, "immutable borrow occurs here" and
  55.                "mutable borrow ends here" can be two separate primary spans.
  57.                The top (parent) message should always have at least one
  58.                primary span, unless it has zero spans. Child messages may have
  59.                zero or more primary spans.
  60.             */
  61.             "is_primary": true,
  62.             /* An array of objects showing the original source code for this
  63.                span. This shows the entire lines of text where the span is
  64.                located. A span across multiple lines will have a separate
  65.                value for each line.
  66.             */
  67.             "text": [
  68.                 {
  69.                     /* The entire line of the original source code. */
  70.                     "text": "    let x = 123;",
  71.                     /* The first character offset of the line of
  72.                        where the span covers this line (1-based, inclusive). */
  73.                     "highlight_start": 9,
  74.                     /* The last character offset of the line of
  75.                        where the span covers this line (1-based, exclusive). */
  76.                     "highlight_end": 10
  77.                 }
  78.             ],
  79.             /* An optional message to display at this span location.
  80.                This is typically null for primary spans.
  81.             */
  82.             "label": null,
  83.             /* An optional string of a suggested replacement for this span to
  84.                solve the issue. Tools may try to replace the contents of the
  85.                span with this text.
  86.             */
  87.             "suggested_replacement": null,
  88.             /* An optional string that indicates the confidence of the
  89.                "suggested_replacement". Tools may use this value to determine
  90.                whether or not suggestions should be automatically applied.
  92.                Possible values may be:
  93.                - "MachineApplicable": The suggestion is definitely what the
  94.                  user intended. This suggestion should be automatically
  95.                  applied.
  96.                - "MaybeIncorrect": The suggestion may be what the user
  97.                  intended, but it is uncertain. The suggestion should result
  98.                  in valid Rust code if it is applied.
  99.                - "HasPlaceholders": The suggestion contains placeholders like
  100.                  `(...)`. The suggestion cannot be applied automatically
  101.                  because it will not result in valid Rust code. The user will
  102.                  need to fill in the placeholders.
  103.                - "Unspecified": The applicability of the suggestion is unknown.
  104.             */
  105.             "suggestion_applicability": null,
  106.             /* An optional object indicating the expansion of a macro within
  107.                this span.
  109.                If a message occurs within a macro invocation, this object will
  110.                provide details of where within the macro expansion the message
  111.                is located.
  112.             */
  113.             "expansion": {
  114.                 /* The span of the macro invocation.
  115.                    Uses the same span definition as the "spans" array.
  116.                 */
  117.                 "span": {/*...*/}
  118.                 /* Name of the macro, such as "foo!" or "#[derive(Eq)]". */
  119.                 "macro_decl_name": "some_macro!",
  120.                 /* Optional span where the relevant part of the macro is
  121.                   defined. */
  122.                 "def_site_span": {/*...*/},
  123.             }
  124.         }
  125.     ],
  126.     /* Array of attached diagnostic messages.
  127.        This is an array of objects using the same format as the parent
  128.        message. Children are not nested (children do not themselves
  129.        contain "children" definitions).
  130.     */
  131.     "children": [
  132.         {
  133.             "message": "`#[warn(unused_variables)]` on by default",
  134.             "code": null,
  135.             "level": "note",
  136.             "spans": [],
  137.             "children": [],
  138.             "rendered": null
  139.         },
  140.         {
  141.             "message": "consider prefixing with an underscore",
  142.             "code": null,
  143.             "level": "help",
  144.             "spans": [
  145.                 {
  146.                     "file_name": "lib.rs",
  147.                     "byte_start": 21,
  148.                     "byte_end": 22,
  149.                     "line_start": 2,
  150.                     "line_end": 2,
  151.                     "column_start": 9,
  152.                     "column_end": 10,
  153.                     "is_primary": true,
  154.                     "text": [
  155.                         {
  156.                             "text": "    let x = 123;",
  157.                             "highlight_start": 9,
  158.                             "highlight_end": 10
  159.                         }
  160.                     ],
  161.                     "label": null,
  162.                     "suggested_replacement": "_x",
  163.                     "suggestion_applicability": "MachineApplicable",
  164.                     "expansion": null
  165.                 }
  166.             ],
  167.             "children": [],
  168.             "rendered": null
  169.         }
  170.     ],
  171.     /* Optional string of the rendered version of the diagnostic as displayed
  172.        by rustc. Note that this may be influenced by the `--json` flag.
  173.     */
  174.     "rendered": "warning: unused variable: `x`\n --> lib.rs:2:9\n  |\n2 |     let x = 123;\n  |         ^ help: consider prefixing with an underscore: `_x`\n  |\n  = note: `#[warn(unused_variables)]` on by default\n\n"
  175. }

Artifact notifications

Artifact notifications are emitted when the —json=artifactsflag is used. They indicate that a file artifact has been savedto disk. More information about emit kinds may be found in the —emitflag documentation.

  1. {
  2.     /* The filename that was generated. */
  3.     "artifact": "libfoo.rlib",
  4.     /* The kind of artifact that was generated. Possible values:
  5.        - "link": The generated crate as specified by the crate-type.
  6.        - "dep-info": The `.d` file with dependency information in a Makefile-like syntax.
  7.        - "metadata": The Rust `.rmeta` file containing metadata about the crate.
  8.        - "save-analysis": A JSON file emitted by the `-Zsave-analysis` feature.
  9.     */
  10.     "emit": "link"
  11. }