Repository navigation
Open
Labels
needs-infoAdditional information needed from the issue authorAdditional information needed from the issue author
Description
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]
Reacted by Sam Rawlins, AteBit and Romjan D. Hossain
Metadata
Metadata
Assignees
Labels
needs-infoAdditional information needed from the issue authorAdditional information needed from the issue author
Activity
szakarias commentedon Jan 21, 2026
Thanks for filing this. Could you provide a reproduction case or a link to the source code where this is failing?
shawkyebrahim2514 commentedon Feb 26, 2026
Hi Sarah,
Reproduction
Run
panaon any Flutter package on Windows:Root Cause
CRLF line ending mismatch. On Windows,
git clonechecks out Flutter SDK.dartfiles with\r\n(CRLF). The Dart analyzer records@docImportbyte offsets based on the raw CRLF file, butelement.documentationCommentnormalizes 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\rstripped from a large doc comment.Verification
core.eol=lf+ re-checkout--dartdoc-version 9.0.0To force LF and confirm:
Why 9.0.2+ only
PR #4173 expanded precaching to all elements, making
_stripDocImports()run on Flutter SDK elements with@docImportfor the first time — exposing the latent offset bug.Workaround
Pinning to dartdoc 9.0.0:
pana --dartdoc-version 9.0.0 .srawlins commentedon Feb 26, 2026
Thanks for the digging, @shawkyebrahim2514 . I'll try to reproduce.
Vorkytaka commentedon Mar 5, 2026
Got the same issue on 9.0.4
Hawks124 commentedon Mar 25, 2026
Environment
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 offset0..9088: 9201is identical to the one reported in this issue.Stack trace
Notes
dart pub global activate dartdoc), so downgrading dartdoc manually has no effect.0..9088: 9201across different packages and reporters suggests this is a consistent bug in how_stripDocImportscalculates string indices with multi-byte UTF-8 characters.ci(pana): pin pana 0.23.12 + clarify dartdoc version range (#39)
ci: add pana score guard on ubuntu-latest + dart format sweep (#39)
atebitftw commentedon Jun 7, 2026
I am also getting this same issue on dartdoc v 9.0.4. What is the best workaround for this?
Expand doc import regression test with multi-line stress case
wyrindev commentedon Sep 29, 2026
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
_stripDocImportsWhen a documentation comment contains
@docImporttogether 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 causedocImport.offsetorrangeEndto exceedcontent.length, resulting in an unhandledRangeErrorfromString.substring().Context loss through
ParallelWaitErrorPackageGraph._precacheLocalDocsprecaches documentation comments in parallel viafutures.wait. An uncaught exception is therefore surfaced asParallelWaitError, obscuring the affected file, element, and source location.2. Changes in PR #4289
Bounds validation
_stripDocImportsclamps substring boundaries to[0, content.length]and only performs the slice whensafeStart < safeEnd, preventing invalid ranges from causing a fatalRangeError.Diagnostic context
DocumentationComment.precacheLocalDocsnow catches and logs failures with the affectedlocationandfullyQualifiedNamebefore rethrowing, preserving actionable diagnostic context.Regression test
Adds
test_docImport_withNonAsciiAndCrlfto cover multi-line comments containing non-ASCII characters and CRLF line endings.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:lib/repro.dart(saved with CRLF\r\nline endings)4. Reproduction & Verification Results
Before Fix (unpatched dartdoc) - Crashes with RangeError
Running
dart doccrashes during local documentation precaching:After Fix (with this PR) - Generates Cleanly
Running the patched
dartdocagainst the exact same project completes successfully:The documentation is generated successfully without any errors or warnings.
All 50 tests in
test/documentation_comment_test.dartpass.drrnbrns commentedon Nov 12, 2026
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.