dart doc crashes on package

[schultek]

Running dart doc on the jaspr package crashes with the exception:

Initialized dartdoc with 575 libraries
Generating docs for library jaspr.dart from package:jaspr/jaspr.dart...

dartdoc 9.0.0 (/Users/kilian/Documents/Work/flutter/flutter/bin/cache/dart-sdk/bin/snapshots/dartdev_aot.dart.snapshot) failed: UnimplementedError: No members on Library.sentinel are accessible
#0      _LibrarySentinel.noSuchMethod (package:dartdoc/src/model/library.dart:18)
dart-lang/sdk#1      _LibrarySentinel.element (package:dartdoc/src/model/library.dart:15)
dart-lang/sdk#2      canonicalLibraryCandidate (package:dartdoc/src/model/canonicalization.dart:15)
dart-lang/sdk#3      ModelElement.canonicalLibrary.<anonymous closure> (package:dartdoc/src/model/model_element.dart:510)
dart-lang/sdk#4      ModelElement.canonicalLibrary (package:dartdoc/src/model/model_element.dart:525)
dart-lang/sdk#5      ModelElement.canonicalLibrary (package:dartdoc/src/model/model_element.dart)
dart-lang/sdk#6      PackageGraph.findCanonicalModelElementFor (package:dartdoc/src/model/package_graph.dart:715)
dart-lang/sdk#7      ModelElement.canonicalModelElement.<anonymous closure> (package:dartdoc/src/model/model_element.dart:478)
dart-lang/sdk#8      ModelElement.canonicalModelElement (package:dartdoc/src/model/model_element.dart:480)
dart-lang/sdk#9      ModelElement.canonicalModelElement (package:dartdoc/src/model/model_element.dart)
dart-lang/sdk#10     ModelElement.href (package:dartdoc/src/model/model_element.dart:619)
dart-lang/sdk#11     MarkdownDocument._makeLinkNode (package:dartdoc/src/markdown_processor.dart:317)
dart-lang/sdk#12     new MarkdownDocument.withElementLinkResolver.<anonymous closure> (package:dartdoc/src/markdown_processor.dart:267)
dart-lang/sdk#13     LinkSyntax._resolveReferenceLink (package:markdown/src/inline_syntaxes/link_syntax.dart:135)
dart-lang/sdk#14     LinkSyntax._tryCreateReferenceLink (package:markdown/src/inline_syntaxes/link_syntax.dart:177)
dart-lang/sdk#15     LinkSyntax.close (package:markdown/src/inline_syntaxes/link_syntax.dart:101)
dart-lang/sdk#16     InlineParser._linkOrImage (package:markdown/src/inline_parser.dart:151)
dart-lang/sdk#17     InlineParser.parse (package:markdown/src/inline_parser.dart:106)
dart-lang/sdk#18     MarkdownDocument._parseInlineContent (package:dartdoc/src/markdown_processor.dart:298)
dart-lang/sdk#19     MarkdownDocument._parseInlineContent (package:dartdoc/src/markdown_processor.dart:303)
dart-lang/sdk#20     MarkdownDocument.parseMarkdownText (package:dartdoc/src/markdown_processor.dart:288)
dart-lang/sdk#21     Documentation._parseDocumentation (package:dartdoc/src/model/documentation.dart:83)
dart-lang/sdk#22     Documentation._renderDocumentation (package:dartdoc/src/model/documentation.dart:64)
dart-lang/sdk#23     Documentation.asOneLiner (package:dartdoc/src/model/documentation.dart:58)
dart-lang/sdk#24     ModelElement.oneLineDoc (package:dartdoc/src/model/model_element.dart:727)
dart-lang/sdk#25     _renderCategory_partial_container_3 (package:dartdoc/src/generator/templates.aot_renderers_for_html.dart:3013)
dart-lang/sdk#26     renderLibrary (package:dartdoc/src/generator/templates.aot_renderers_for_html.dart:1016)
dart-lang/sdk#27     HtmlAotTemplates.renderLibrary (package:dartdoc/src/generator/templates.dart:156)
dart-lang/sdk#28     GeneratorBackend.generateLibrary (package:dartdoc/src/generator/generator_backend.dart:190)
dart-lang/sdk#29     HtmlGeneratorBackend.generateLibrary (package:dartdoc/src/generator/html_generator_backend.dart:60)
dart-lang/sdk#30     Generator._generateDocs (package:dartdoc/src/generator/generator.dart:174)
dart-lang/sdk#31     Generator.generate (package:dartdoc/src/generator/generator.dart:54)
<asynchronous suspension>
dart-lang/sdk#32     Dartdoc.generateDocsBase (package:dartdoc/src/dartdoc.dart:199)
<asynchronous suspension>
dart-lang/sdk#33     Dartdoc.generateDocs (package:dartdoc/src/dartdoc.dart:237)
<asynchronous suspension>
dart-lang/sdk#34     Dartdoc.executeGuarded.<anonymous closure> (package:dartdoc/src/dartdoc.dart:269)
<asynchronous suspension>

This also shows up on the pub score of the package and causes the API docs to not generate.

Related: schultek/jaspr#709

---

• Dart SDK version: 3.11.0-271.0.dev (dev) (Tue Dec 23 08:03:35 2025 -0800) on "macos_arm64"

[FMorschel]

CC @szakarias

[lrhn]

Seems like it's missing a Library.sentinel test before using the element.library.

(I tried writing a fix. If it's too much of a change, a single line change can fix this issue.)

[midiakiasat]

This crash is due to violating the Library.sentinel invariant.

Library.sentinel is a valid placeholder during canonicalization and must never have its element accessed. The current code path calls element.library without guarding against the sentinel case, which triggers the UnimplementedError.

Invariant to enforce:

• If a canonicalization candidate is Library.sentinel, short-circuit and skip it.
• Never dereference members on Library.sentinel.

A simple sentinel check before accessing element.library should be sufficient.

[schultek]

@lrhn thanks for the fix, the original error seems to be fixed. But now I get a new one when running latest dartdoc on jaspr:

Documenting jaspr...
Discovering libraries...
Linking elements...
Precaching local docs for 1020059 elements...
Initialized dartdoc with 574 libraries
Generating docs for library jaspr.dart from package:jaspr/jaspr.dart...
dartdoc 9.0.2 (/private/var/folders/9x/4yq3l6pd31q1bs4st2fc3fdm0000gp/T/pana.1770304964232.8gImqb/pub-cache/global_packages/dartdoc/bin/dartdoc.dart-3.11.0-253.0.dev.snapshot) failed: Null check operator used on a null value
#0      ModelElement._constructFromElementDeclaration (package:dartdoc/src/model/model_element.dart:297:41)
#1      new ModelElement.for_ (package:dartdoc/src/model/model_element.dart:250:40)
#2      new ModelElement.forElement (package:dartdoc/src/model/model_element.dart:112:25)
#3      Nameable.getModelForElement (package:dartdoc/src/model/nameable.dart:73:20)
#4      CommentReferable._lookupViaScope (package:dartdoc/src/model/comment_referable.dart:142:29)
#5      CommentReferable.referenceBy (package:dartdoc/src/model/comment_referable.dart:58:20)
#6      _getMatchingLinkElement (package:dartdoc/src/markdown_processor.dart:176:15)
#7      getMatchingLinkElement (package:dartdoc/src/markdown_processor.dart:187:16)
#8      MarkdownDocument._makeLinkNode (package:dartdoc/src/markdown_processor.dart:313:18)
#9      new MarkdownDocument.withElementLinkResolver.<anonymous closure> (package:dartdoc/src/markdown_processor.dart:267:51)
#10     LinkSyntax._resolveReferenceLink (package:markdown/src/inline_syntaxes/link_syntax.dart:137:36)
#11     LinkSyntax._tryCreateReferenceLink (package:markdown/src/inline_syntaxes/link_syntax.dart:177:18)
#12     LinkSyntax.close (package:markdown/src/inline_syntaxes/link_syntax.dart:103:12)
#13     InlineParser._linkOrImage (package:markdown/src/inline_parser.dart:150:32)
#14     InlineParser.parse (package:markdown/src/inline_parser.dart:106:9)
#15     MarkdownDocument._parseInlineContent (package:dartdoc/src/markdown_processor.dart:298:67)
#16     MarkdownDocument._parseInlineContent (package:dartdoc/src/markdown_processor.dart:303:9)
#17     MarkdownDocument.parseMarkdownText (package:dartdoc/src/markdown_processor.dart:288:5)
#18     Documentation._parseDocumentation (package:dartdoc/src/model/documentation.dart:83:21)
#19     Documentation._renderDocumentation (package:dartdoc/src/model/documentation.dart:64:23)
#20     Documentation.asOneLiner (package:dartdoc/src/model/documentation.dart:58:5)
#21     ModelElement.oneLineDoc (package:dartdoc/src/model/model_element.dart:737:49)
#22     _renderCategory_partial_container_3 (package:dartdoc/src/generator/templates.aot_renderers_for_html.dart:2908:25)
#23     renderLibrary (package:dartdoc/src/generator/templates.aot_renderers_for_html.dart:1015:20)
#24     HtmlAotTemplates.renderLibrary (package:dartdoc/src/generator/templates.dart:156:30)
#25     GeneratorBackend.generateLibrary (package:dartdoc/src/generator/generator_backend.dart:190:29)
#26     HtmlGeneratorBackend.generateLibrary (package:dartdoc/src/generator/html_generator_backend.dart:60:11)
#27     Generator._generateDocs (package:dartdoc/src/generator/generator.dart:174:27)
#28     Generator.generate (package:dartdoc/src/generator/generator.dart:54:25)
<asynchronous suspension>
#29     Dartdoc.generateDocsBase (package:dartdoc/src/dartdoc.dart:199:5)
<asynchronous suspension>
#30     Dartdoc.generateDocs (package:dartdoc/src/dartdoc.dart:237:24)
<asynchronous suspension>
#31     Dartdoc.executeGuarded.<anonymous closure> (package:dartdoc/src/dartdoc.dart:269:9)
<asynchronous suspension>

[srawlins]

@schultek did you get this error documenting the latest jaspr package? 0.22.2?

[schultek]

Yes, you can also see it on pub.dev

[srawlins]

I can reproduce; it is first failing to find the NotificationListener in package:jaspr/src/components/notification_listener.dart. And indeed I think dartdoc is not finding that library, in some sense; it only has about 10 libraries from the jaspr package in its "package graph." I'll continue to investigate.

[srawlins]

Oh this is a curious state. The only reference in the jaspr package to it's notification_listener.dart library is from a @docImport:

$ git grep 'notification_listener.dart'
lib/src/framework/framework.dart:/// @docImport '../components/notification_listener.dart';
$

I think then that this is just a bug in our code that reaches out to find all libraries reachable from the public libraries.

[alextekartik]

For info same issue in sembast_web using and tried locally using dartdoc v9.0.2 dart 3.11.0

$ dartdoc
Documenting sembast_web...
Discovering libraries...
[--------------------------------------------------------------------------------------------------------------------------------------------------------] (100.00%)

Linking elements...
[--------------------------------------------------------------------------------------------------------------------------------------------------------] (100.00%)

Precaching local docs for 175609 elements...
[--------------------------------------------------------------------------------------------------------------------------------------|                 ] (89.15%)
dartdoc 9.0.2 (/home/alex/.pub-cache/global_packages/dartdoc/bin/dartdoc.dart-3.11.0.snapshot) failed: Null check operator used on a null value
#0      GetterSetterCombo.characterLocation (package:dartdoc/src/model/getter_setter_combo.dart:132:18)
#1      ModelElement.location (package:dartdoc/src/model/model_element.dart:558:9)
#2      PackageWarning.messageForWarnable (package:dartdoc/src/warnings.dart:357:66)
#3      PackageGraph._warnOnElement (package:dartdoc/src/model/package_graph.dart:473:34)
#4      PackageGraph.warnOnElement (package:dartdoc/src/model/package_graph.dart:404:5)
#5      Warnable.warn (package:dartdoc/src/warnings.dart:107:18)
#6      _Canonicalization.canonicalLibraryCandidate (package:dartdoc/src/model/canonicalization.dart:135:21)
#7      canonicalLibraryCandidate (package:dartdoc/src/model/canonicalization.dart:64:8)
#8      ModelElement.canonicalLibrary.<anonymous closure> (package:dartdoc/src/model/model_element.dart:515:11)
#9      ModelElement.canonicalLibrary (package:dartdoc/src/model/model_element.dart:530:4)
#10     ModelElement.canonicalLibrary (package:dartdoc/src/model/model_element.dart)
#11     PackageGraph.findCanonicalModelElementFor (package:dartdoc/src/model/package_graph.dart:715:32)
#12     ModelElement.canonicalModelElement.<anonymous closure> (package:dartdoc/src/model/model_element.dart:483:25)
#13     ModelElement.canonicalModelElement (package:dartdoc/src/model/model_element.dart:485:4)
#14     ModelElement.canonicalModelElement (package:dartdoc/src/model/model_element.dart)
#15     PackageGraph._precacheLocalDocs (package:dartdoc/src/model/package_graph.dart:167:13)
#16     PackageGraph.initializePackageGraph (package:dartdoc/src/model/package_graph.dart:119:11)
#17     PubPackageBuilder.buildPackageGraph (package:dartdoc/src/model/package_builder.dart:152:22)
<asynchronous suspension>
#18     Dartdoc.generateDocsBase (package:dartdoc/src/dartdoc.dart:193:24)
<asynchronous suspension>
#19     Dartdoc.generateDocs (package:dartdoc/src/dartdoc.dart:237:24)
<asynchronous suspension>
#20     Dartdoc.executeGuarded.<anonymous closure> (package:dartdoc/src/dartdoc.dart:269:9)
<asynchronous suspension>

Strangly, dart doc works fine though...

$ dart doc
Documenting sembast_web...
Discovering libraries...
[--------------------------------------------------------------------------------------------------------------------------------------------------------] (100.00%)

Linking elements...
[--------------------------------------------------------------------------------------------------------------------------------------------------------] (100.00%)

Precaching local docs for 175609 elements...
[--------------------------------------------------------------------------------------------------------------------------------------------------------] (100.00%)

Initialized dartdoc with 323 libraries
Generating docs for library sembast_web_interop.dart from package:sembast_web/sembast_web_interop.dart...
Generating docs for library sembast_web.dart from package:sembast_web/sembast_web.dart...
Generating docs for library sembast_web_html.dart from package:sembast_web/sembast_web_html.dart...
Found 0 warnings and 0 errors.
Documented 3 public libraries in 4.3 seconds
Success! Docs generated into /home/alex/tekartik/devx/git/github.com/tekartik/sembast.dart/sembast_web/doc/api

But the pub package score page seems to report that dartdoc is used: https://pub.dev/packages/sembast_web/score