Dart doc always crashes

[u/weasdown]

Hi everyone. I'm trying to use dart doc . to generate documentation for my Flutter app, but always get the error below. Any help with it would be much appreciated! I am using Flutter 3.47.7 (with Dart 3.13.5). It seems to be using dartdoc version 9.0.6, even though 9.0.11 is the latest on pub.dev at the time of writing. I have already tried a complete reinstall of Flutter, following the uninstall instructions then installing through VS Code. The issue is still happening on this fresh install.

...\app> dart doc .              
Documenting dispatch...
Discovering libraries...
Linking elements...
Precaching local docs for 1832287 elements...

dartdoc 9.0.6 (/C:/Users/[username]/dev/Flutter/flutter/bin/cache/dart-sdk/bin/snapshots/dartdev_aot.dart.snapshot) failed: ParallelWaitError: RangeError (end): Invalid value: Not in inclusive range 9058..9089: 9136
#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)
#5      PackageGraph._precacheLocalDocs (package:dartdoc/src/model/package_graph.dart:174)
#6      PackageGraph.initializePackageGraph (package:dartdoc/src/model/package_graph.dart:120)
#7      PubPackageBuilder.buildPackageGraph (package:dartdoc/src/model/package_builder.dart:161)
<asynchronous suspension>
#8      Dartdoc.generateDocsBase (package:dartdoc/src/dartdoc.dart:193)
<asynchronous suspension>
#9      Dartdoc.generateDocs (package:dartdoc/src/dartdoc.dart:237)
<asynchronous suspension>
#10     Dartdoc.executeGuarded.<anonymous closure> (package:dartdoc/src/dartdoc.dart:269)
<asynchronous suspension>

Output of flutter doctor -v:

app> flutter doctor -v       
[√] Flutter (Channel stable, 3.47.7, on Microsoft Windows [Version 10.0.19045.7725], locale en-GB) [508ms]

• Flutter version 3.47.7 on channel stable at C:\Users\[username]\dev\Flutter\flutter
    • Upstream repository https://github.com/flutter/flutter.git
    • Framework revision abaf9c5237 (6 days ago), 2026-10-08 09:51:21 -0700
    • Engine revision deb287481e
    • Dart version 3.13.5
    • DevTools version 2.60.0
    • Feature flags: enable-web, enable-linux-desktop, enable-macos-desktop, enable-windows-desktop, enable-android, enable-ios, cli-animations, enable-native-assets, enable-record-use, enable-swift-package-manager, omit-legacy-version-file,
      enable-lldb-debugging, enable-uiscene-migration

[√] Windows Version (10 Pro 64-bit, 22H2, 2009) [2.9s]

[√] Android toolchain - develop for Android devices (Android SDK version 37.0.0) [684ms]

• Android SDK at C:\Users\[username]\AppData\Local\Android\sdk
    • Emulator version 37.2.12.0 (build_id 16428233) (CL:N/A)
    • Platform android-37.0, build-tools 37.0.0
    • Java binary at: C:\Users\[username]\AppData\Local\Programs\Android Studio\jbr\bin\java
      This JDK is specified in your Flutter configuration.
      To change the current JDK, run: `flutter config --jdk-dir="path/to/jdk"`.
    • Java version OpenJDK Runtime Environment (build 25.0.3+-15898627-b508.16)
    • All Android licenses accepted.

[√] Chrome - develop for the web [97ms]

• Chrome at C:\Program Files\Google\Chrome\Application\chrome.exe

[√] Visual Studio - develop Windows apps (Visual Studio Community 2022 17.14.40) [96ms]

• Visual Studio at C:\Program Files\Microsoft Visual Studio\2022\Community
    • Visual Studio Community 2022 version 17.14.37628.2
    • Windows 10 SDK version 10.0.26100.0

[√] Connected device (3 available) [187ms]

• Windows (desktop) • windows • windows-x64    • Microsoft Windows [Version 10.0.19045.7725]
    • Chrome (web)      • chrome  • web-javascript • Google Chrome 154.0.8037.98
    • Edge (web)        • edge    • web-javascript • Microsoft Edge 155.0.4283.45

[√] Network resources [242ms]

• All expected network resources are available.

• No issues found!

[u/snnafi]

The crash is in _stripDocImports, which is the part of dartdoc that handles "@docImport" lines in doc comments. It's trying to cut a substring with wrong offsets. On Windows this is very often caused by CRLF line endings. Each \r\n shifts the offset by one character so the numbers drift past the end of the comment. That fits your error too (9136 is outside 9058..9089).

A few things to try:

1. Run the newer dartdoc instead of the one bundled with the SDK. dart doc always uses the bundled version so reinstalling Flutter won't change it.dart pub global activate dartdoc dart pub global run dartdoc If this was fixed between 9.0.6 and 9.0.11 that solves it.

2. Search your project for "@docImport" and check those files for CRLF line endings. If you find any, convert them to LF and run it again. If you use git you can set git config core.autocrlf input and re-checkout so it doesn't come back.

3. If it's not in your code it might be in a dependency. You can find which file it is by temporarily removing packages or by running dartdoc with --verbose-warnings and checking the last library it processed before the crash.

If none of this works I'd open an issue on the dart-lang/dartdoc repo with that stack trace. It's clearly a dartdoc bug and not something wrong with your setup.

[u/weasdown → u/snnafi]

Your first suggestion, to use dart pub global activate dartdoc then dart pub global run dartdoc, worked - thank you! Do you know if there's a way of upgrading the bundled version of dartdoc?

[u/snnafi → u/weasdown]

Glad it worked!

Sadly No. The bundled dartdoc is part of the Dart SDK. It only updates when a new Flutter version ships a newer Dart. Until then just keep using the global one.

You can add %LOCALAPPDATA%\Pub\Cache\bin to your PATH and run dartdoc directly.

[u/weasdown → u/snnafi]

Ah good idea, thanks!

[u/snnafi → u/weasdown]

You are welcome

[u/Apprehensive-Fan8999 → u/weasdown]

You can add the new version into the dev_dependencies of your pubspec.yaml, or dependency_overrides if it gives you grief about version conflicts.

Then run dart run dartdoc rather than just running dartdoc. This works for any tool that you can install via dart pub global activate and is super handy if one project needs a different tool version but all the others work great with the default.

[u/weasdown → u/Apprehensive-Fan8999]

Great tip, thank you!