Skip to content

Pana Dartdoc Crashing #4180

Open
Open

Description

@shawkyebrahim2514

The issue is that dartdoc 9.0.2 has a bug (RangeError in _stripDocImports) that crashes when processing documentation comments, causing pana to fail the documentation check

  • Activated pana 0.23.8
  • dartdoc 9.0.2
WARNING: `dartdoc` failed:
                                    Discovering libraries...
                                    Linking elements...
                                    Precaching local docs for 931342 elements...
                                    dartdoc 9.0.2 (/C:/Users/cloudtest/AppData/Local/Temp/pana.1768941083324.4da2768/pub-cache/global_packages/dartdoc/bin/dartdoc.dart-3.10.7.snapshot) failed: ParallelWaitError: RangeError (end): Invalid value: Not in inclusive range 0..9088: 9201
                                    #0      RangeError.checkValidRange (dart:core/errors.dart:392:9)
                                    dart-lang/pub-dev#1      _StringBase.substring (dart:core-patch/string_patch.dart:440:27)
                                    dart-lang/pub-dev#2      DocumentationComment._stripDocImports (package:dartdoc/src/model/documentation_comment.dart:553:28)
                                    dart-lang/pub-dev#3      DocumentationComment.processComment (package:dartdoc/src/model/documentation_comment.dart:94:16)
                                    dart-lang/pub-dev#4      DocumentationComment._buildDocumentationBase (package:dartdoc/src/model/documentation_comment.dart:717:25)
                                    dart-lang/pub-dev#5      DocumentationComment.precacheLocalDocs (package:dartdoc/src/model/documentation_comment.dart:688:33)
                                    dart-lang/pub-dev#6      PackageGraph._precacheLocalDocs (package:dartdoc/src/model/package_graph.dart:173:27)
                                    dart-lang/pub-dev#7      PackageGraph.initializePackageGraph (package:dartdoc/src/model/package_graph.dart:119:11)
                                    dart-lang/pub-dev#8      PubPackageBuilder.buildPackageGraph (package:dartdoc/src/model/package_builder.dart:152:22)
                                    <asynchronous suspension>
                                    dart-lang/pub-dev#9      Dartdoc.generateDocsBase (package:dartdoc/src/dartdoc.dart:193:24)
                                    <asynchronous suspension>
                                    dart-lang/pub-dev#10     Dartdoc.generateDocs (package:dartdoc/src/dartdoc.dart:237:24)
                                    <asynchronous suspension>
                                    dart-lang/pub-dev#11     Dartdoc.executeGuarded.<anonymous closure> (package:dartdoc/src/dartdoc.dart:269:9)
                                    <asynchronous suspension>

## ✗ Provide documentation (10 / 20)
### [x] 0/10 points: 20% or more of the public API has dartdoc comments

OUT:
Discovering libraries...
Linking elements...
Precaching local docs for 931342 elements...
ERR:
dartdoc 9.0.2 (/C:/Users/cloudtest/AppData/Local/Temp/pana.1768986759630.29df6864/pub-cache/global_packages/dartdoc/bin/dartdoc.dart-3.10.7.snapshot) failed: ParallelWaitError: RangeError (end): [...]
#0      RangeError.checkValidRange (dart:core/errors.dart:392:9)
dart-lang/pub-dev#1      _StringBase.substring (dart:core-patch/string_patch.dart:440:27)
dart-lang/pub-dev#2      DocumentationComment._stripDocImports (package:dartdoc/src/model/documentation_comment.dart:553:28)
dart-lang/pub-dev#3      DocumentationComment.processComment (package:dartdoc/src/model/documentation_comment.dart:94:16)
dart-lang/pub-dev#4      DocumentationComment._buildDocumentationBase (package:dartdoc/src/model/documentation_comment.dart:717:25)
dart-lang/pub-dev#5      DocumentationComment.precacheLocalDocs (package:dartdoc/src/model/documentation_comment.dart:688:33)
dart-lang/pub-dev#6      PackageGraph._precacheLocalDocs (package:dartdoc/src/model/package_graph.dart:173:27)
dart-lang/pub-dev#7      PackageGraph.initializePackageGraph (package:dartdoc/src/model/package_graph.dart:119:11)
dart-lang/pub-dev#8      PubPackageBuilder.buildPackageGraph (package:dartdoc/src/model/package_builder.dart:152:22)
[7 more lines]

Activity

  1. szakarias commented on Jan 21, 2026

    @szakarias
    Collaborator

    Thanks for filing this. Could you provide a reproduction case or a link to the source code where this is failing?

  2. added
    needs-infoAdditional information needed from the issue author
    on Jan 21, 2026
  3. shawkyebrahim2514 commented on Feb 26, 2026

    @shawkyebrahim2514
    Author

    Hi Sarah,

    Reproduction

    Run pana on any Flutter package on Windows:

    pana --flutter-sdk "<path_to_flutter>" --exit-code-threshold 0 .

    Root Cause

    CRLF line ending mismatch. On Windows, git clone checks out Flutter SDK .dart files with \r\n (CRLF). The Dart analyzer records @docImport byte offsets based on the raw CRLF file, but element.documentationComment normalizes to \n (LF) only. _stripDocImports() then uses the larger CRLF offsets to call .substring() on the shorter LF string → RangeError.

    The error Not in inclusive range 0..9088: 9201 — the difference of 113 matches ~113 lines of \r stripped from a large doc comment.

    Verification

    Test Line Endings dartdoc Result
    Default Windows clone CRLF 9.0.2 Crash
    Default Windows clone CRLF 9.0.3 Crash
    Forced core.eol=lf + re-checkout LF 9.0.3 Pass (160/160)
    Pinned --dartdoc-version 9.0.0 CRLF 9.0.0 Pass

    To force LF and confirm:

    cd "<flutter_sdk>"
    git config core.autocrlf false
    git config core.eol lf
    git rm --cached -r .
    git reset --hard HEAD
    # Then re-run pana — succeeds

    Why 9.0.2+ only

    PR #4173 expanded precaching to all elements, making _stripDocImports() run on Flutter SDK elements with @docImport for the first time — exposing the latent offset bug.

    Workaround

    Pinning to dartdoc 9.0.0: pana --dartdoc-version 9.0.0 .

  4. srawlins commented on Feb 26, 2026

    @srawlins
    Member

    Thanks for the digging, @shawkyebrahim2514 . I'll try to reproduce.

  5. Vorkytaka commented on Mar 5, 2026

    @Vorkytaka

    Got the same issue on 9.0.4

    2026-03-05 22:52:53.086417 INFO: Running `dart.exe pub global run dartdoc --output C:\Users\solid\AppData\Local\Temp\pana.1772740349977.3d4a935f\doc --sanitize-html --max-file-count 10000000 --max-total-size 2147483648 --no-validate-links --sdk-dir C:\Users\solid\fvm\versions\3.35.6\bin\cache\dart-sdk`...            
    2026-03-05 22:53:25.392744 WARNING: `dartdoc` failed:
                                        Documenting puer_flutter...                                                                                                
                                        Discovering libraries...                                                                                                   
                                        Linking elements...                                                                                                        
                                        Precaching local docs for 646464 elements...                                                                               
                                        dartdoc 9.0.4 (/C:/Users/solid/AppData/Local/Temp/pana.1772740349977.3d4a935f/pub-cache/global_packages/dartdoc/bin/dartdoc.dart-3.9.2.snapshot) failed: ParallelWaitError: RangeError (end): Invalid value: Not in inclusive range 0..9088: 9201                                         
                                        #0      RangeError.checkValidRange (dart:core/errors.dart:392:9)                                                           
                                        #1      _StringBase.substring (dart:core-patch/string_patch.dart:440:27)                                                   
                                        #2      DocumentationComment._stripDocImports (package:dartdoc/src/model/documentation_comment.dart:869:28)                
                                        #3      DocumentationComment.processComment (package:dartdoc/src/model/documentation_comment.dart:101:18)                  
                                        #4      DocumentationComment.precacheLocalDocs (package:dartdoc/src/model/documentation_comment.dart:999:33)               
                                        #5      PackageGraph._precacheLocalDocs (package:dartdoc/src/model/package_graph.dart:172:27)                              
                                        #6      PackageGraph.initializePackageGraph (package:dartdoc/src/model/package_graph.dart:118:11)                          
                                        #7      PubPackageBuilder.buildPackageGraph (package:dartdoc/src/model/package_builder.dart:161:22)                        
                                        <asynchronous suspension>                                                                                                  
                                        #8      Dartdoc.generateDocsBase (package:dartdoc/src/dartdoc.dart:193:24)                                                 
                                        <asynchronous suspension>                                                                                                  
                                        #9      Dartdoc.generateDocs (package:dartdoc/src/dartdoc.dart:237:24)                                                     
                                        <asynchronous suspension>                                                                                                  
                                        #10     Dartdoc.executeGuarded.<anonymous closure> (package:dartdoc/src/dartdoc.dart:269:9)                                
                                        <asynchronous suspension>              
    
  6. Hawks124 commented on Mar 25, 2026

    @Hawks124

    Environment

    • dartdoc: 9.0.4
    • Dart SDK: 3.10.0
    • OS: Windows 10
    • pana: 0.23.x

    Description

    Same crash as reported here, but with dartdoc 9.0.4. Running pana . on my package causes dartdoc to crash during the documentation check, resulting in 150/160 instead of 160/160.

    The issue occurs with a package that contains UTF-8 multi-byte characters (emojis 💡, em-dashes —, arrows →) inside /// doc comments. The offset 0..9088: 9201 is identical to the one reported in this issue.

    Stack trace

    dartdoc 9.0.4 failed: ParallelWaitError: RangeError (end): Invalid value: Not in inclusive range 0..9088: 9201
    #0      RangeError.checkValidRange (dart:core/errors.dart:392:9)
    #1      _StringBase.substring (dart:core-patch/string_patch.dart:440:27)
    #2      DocumentationComment._stripDocImports (package:dartdoc/src/model/documentation_comment.dart:869:28)
    #3      DocumentationComment.processComment (package:dartdoc/src/model/documentation_comment.dart:101:18)
    #4      DocumentationComment.precacheLocalDocs (package:dartdoc/src/model/documentation_comment.dart:999:33)
    #5      PackageGraph._precacheLocalDocs (package:dartdoc/src/model/package_graph.dart:172:27)
    #6      PackageGraph.initializePackageGraph (package:dartdoc/src/model/package_graph.dart:118:11)
    #7      PubPackageBuilder.buildPackageGraph (package:dartdoc/src/model/package_builder.dart:161:22)
    

    Notes

    • Pana reinstalls dartdoc during its run (dart pub global activate dartdoc), so downgrading dartdoc manually has no effect.
    • The identical offset 0..9088: 9201 across different packages and reporters suggests this is a consistent bug in how _stripDocImports calculates string indices with multi-byte UTF-8 characters.
    • Workaround: none found so far.
  7. atebitftw commented on Jun 7, 2026

    @atebitftw

    I am also getting this same issue on dartdoc v 9.0.4. What is the best workaround for this?

  8. wyrindev commented on Sep 29, 2026

    @wyrindev

    I was able to reproduce and investigate this issue on Windows. The failure appears to be caused by an invalid source offset reaching DocumentationComment._stripDocImports. I submitted a fix in PR #4289, along with a regression test and additional diagnostics.

    Details and verification are below.

    1. Root Cause

    • Invalid substring range in _stripDocImports
      When a documentation comment contains @docImport together with multi-line text, non-ASCII characters (such as em-dashes or emoji), and CRLF (\r\n) line endings, source offsets can become inconsistent with Dart string indices. This may cause docImport.offset or rangeEnd to exceed content.length, resulting in an unhandled RangeError from String.substring().

    • Context loss through ParallelWaitError
      PackageGraph._precacheLocalDocs precaches documentation comments in parallel via futures.wait. An uncaught exception is therefore surfaced as ParallelWaitError, obscuring the affected file, element, and source location.

    2. Changes in PR #4289

    1. Bounds validation
      _stripDocImports clamps substring boundaries to [0, content.length] and only performs the slice when safeStart < safeEnd, preventing invalid ranges from causing a fatal RangeError.

    2. Diagnostic context
      DocumentationComment.precacheLocalDocs now catches and logs failures with the affected location and fullyQualifiedName before rethrowing, preserving actionable diagnostic context.

    3. Regression test
      Adds test_docImport_withNonAsciiAndCrlf to cover multi-line comments containing non-ASCII characters and CRLF line endings.

    4. Changelog
      Adds an entry under ## 9.0.10-wip.

    3. Minimal Reproduction

    A standalone minimal reproduction can be created with the following files:

    pubspec.yaml:

    name: repro
    description: Minimal reproduction case for dartdoc RangeError #4180.
    version: 1.0.0
    environment:
      sdk: ">=3.3.0 <4.0.0"
    lib/repro.dart (saved with CRLF \r\n line endings)
    /// Line 1 — description with em-dash — details
    /// Line 2 — description with em-dash — details
    /// Line 3 — description with em-dash — details
    /// Line 4 — description with em-dash — details
    /// Line 5 — description with em-dash — details
    /// Line 6 — description with em-dash — details
    /// Line 7 — description with em-dash — details
    /// Line 8 — description with em-dash — details
    /// Line 9 — description with em-dash — details
    /// Line 10 — description with em-dash — details
    /// Line 11 — description with em-dash — details
    /// Line 12 — description with em-dash — details
    /// Line 13 — description with em-dash — details
    /// Line 14 — description with em-dash — details
    /// Line 15 — description with em-dash — details
    /// Line 16 — description with em-dash — details
    /// Line 17 — description with em-dash — details
    /// Line 18 — description with em-dash — details
    /// Line 19 — description with em-dash — details
    /// Line 20 — description with em-dash — details
    /// Line 21 — description with em-dash — details
    /// Line 22 — description with em-dash — details
    /// Line 23 — description with em-dash — details
    /// Line 24 — description with em-dash — details
    /// Line 25 — description with em-dash — details
    /// Line 26 — description with em-dash — details
    /// Line 27 — description with em-dash — details
    /// Line 28 — description with em-dash — details
    /// Line 29 — description with em-dash — details
    /// Line 30 — description with em-dash — details
    /// Line 31 — description with em-dash — details
    /// Line 32 — description with em-dash — details
    /// Line 33 — description with em-dash — details
    /// Line 34 — description with em-dash — details
    /// Line 35 — description with em-dash — details
    /// Line 36 — description with em-dash — details
    /// Line 37 — description with em-dash — details
    /// Line 38 — description with em-dash — details
    /// Line 39 — description with em-dash — details
    /// Line 40 — description with em-dash — details
    /// Line 41 — description with em-dash — details
    /// Line 42 — description with em-dash — details
    /// Line 43 — description with em-dash — details
    /// Line 44 — description with em-dash — details
    /// Line 45 — description with em-dash — details
    /// Line 46 — description with em-dash — details
    /// Line 47 — description with em-dash — details
    /// Line 48 — description with em-dash — details
    /// Line 49 — description with em-dash — details
    /// Line 50 — description with em-dash — details
    /// Line 51 — description with em-dash — details
    /// Line 52 — description with em-dash — details
    /// Line 53 — description with em-dash — details
    /// Line 54 — description with em-dash — details
    /// Line 55 — description with em-dash — details
    /// Line 56 — description with em-dash — details
    /// Line 57 — description with em-dash — details
    /// Line 58 — description with em-dash — details
    /// Line 59 — description with em-dash — details
    /// Line 60 — description with em-dash — details
    ///
    /// @docImport 'dart:math';
    void test() {}

    4. Reproduction & Verification Results

    Before Fix (unpatched dartdoc) - Crashes with RangeError

    Running dart doc crashes during local documentation precaching:

    Precaching local docs for 109122 elements...
    dartdoc failed: ParallelWaitError: RangeError (end): Invalid value: Not in inclusive range 3941..3942: 3991
    #0      RangeError.checkValidRange (dart:core/errors.dart:392)
    #1      _StringBase.substring (dart:core-patch/string_patch.dart:437)
    #2      DocumentationComment._stripDocImports (package:dartdoc/src/model/documentation_comment.dart:931)
    #3      DocumentationComment.processComment (package:dartdoc/src/model/documentation_comment.dart:103)
    #4      DocumentationComment.precacheLocalDocs (package:dartdoc/src/model/documentation_comment.dart:1050)
    After Fix (with this PR) - Generates Cleanly

    Running the patched dartdoc against the exact same project completes successfully:

    Documenting repro...
    Discovering libraries...
    Linking elements...
    Precaching local docs for 109122 elements...
    Initialized dartdoc with 55 libraries
    Generating docs for library repro.dart...
    Validating links...
    Found 0 warnings and 0 errors.
    Documented 1 public library in 22.4 seconds
    Success! Docs generated into doc/api

    The documentation is generated successfully without any errors or warnings.

    All 50 tests in test/documentation_comment_test.dart pass.

  9. drrnbrns commented on Nov 12, 2026

    @drrnbrns

    FYI I was seeing this crash in Flutter 3.47.0, but after upgrading to Flutter 3.50 (Dart SDK version: 3.14.0 (stable) (Wed Nov 4 16:28:39 2026 -0800) on "windows_x64"), it seems to be working fine.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    needs-infoAdditional information needed from the issue author

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions