apple/pkl · error · DocGeneratorException

Failed to load class path resource `$resourceName`.

Error message

Failed to load class path resource `$resourceName`.

What it means

getResourceAsStream loads a template/resource from the classpath under org/pkl/doc/. If the classloader cannot find the named resource, it throws a DocGeneratorException naming the missing resource. This indicates the pkl-doc library's bundled resources are absent from the runtime classpath.

Solutions

Rebuild/reinstall pkl-doc so its bundled resources under org/pkl/doc/ are on the classpath.
If using shadow/proguard/minimization, exclude org/pkl/doc/** resources from stripping.
For GraalVM native-image, register org/pkl/doc/** resources in resource-config.
Verify the resource name passed to copyResource matches an existing bundled file.

Example fix

// before (shadowJar strips resources)
shadowJar {
  minimize()
}
// after
shadowJar {
  minimize { exclude(dependency("org.pkl-lang:.*:.*")) }
}

Defensive patterns

Strategy: try-catch

Validate before calling

check(Thread.currentThread().contextClassLoader.getResource("org/pkl/doc/") != null) { "pkl-doc resources missing from classpath" }

Type guard

fun hasDocResource(name: String) = getResourceAsStreamOrNull(name) != null

Try / catch

try { copyResource(name) } catch (e: DocGeneratorException) { logger.error("Missing bundled resource: ${e.message}; reinstall pkl-doc") }

Prevention

Disable minimization/proguard stripping of org/pkl/doc/** resources
Register resources in GraalVM native-image config
Smoke-test resource loading after packaging changes
Use getResourceAsStreamOrNull for soft checks

When it happens

Trigger: copyResource being asked for a resource name that is not on the classpath, e.g. a packaged jar missing its resources, a custom classloader (Shade/Gradle shadow) stripping resources, or a typo'd resource name.

Common situations: Shadow/fat-jar builds excluding non-class resources, GraalVM native-image without resource inclusion config, running pkl-doc from an incompletely assembled distribution.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of apple/pkl@f3efcbfc9b (2026-09-08). Data as JSON: /api/errors/23d2fd23d4a4ccae. Report an issue: GitHub.

Appendix: source

Thrown at pkl-doc/src/main/kotlin/org/pkl/doc/Util.kt:40

import java.nio.file.Path
import java.nio.file.StandardCopyOption
import kotlin.io.path.createParentDirectories
import org.pkl.core.*
import org.pkl.core.util.IoUtils
import org.pkl.parser.Lexer

// overwrites any existing file
internal fun copyResource(resourceName: String, targetDir: Path) {
  val targetFile = targetDir.resolve(resourceName).apply { createParentDirectories() }
  Files.copy(getResourceAsStream(resourceName), targetFile, StandardCopyOption.REPLACE_EXISTING)
}

internal fun getResourceAsStreamOrNull(resourceName: String): InputStream? =
  Thread.currentThread().contextClassLoader.getResourceAsStream("org/pkl/doc/$resourceName")

internal fun getResourceAsStream(resourceName: String): InputStream =
  getResourceAsStreamOrNull(resourceName)
    ?: throw DocGeneratorException("Failed to load class path resource `$resourceName`.")

internal val ModuleSchema?.hasListedClass: Boolean
  get() = this != null && allClasses.any { !it.value.isUnlisted }

internal val ModuleSchema?.hasListedTypeAlias: Boolean
  get() = this != null && allTypeAliases.any { !it.value.isUnlisted }

internal val PClass?.hasListedProperty: Boolean
  get() = this != null && allProperties.any { !it.value.isUnlisted }

internal val PClass?.hasListedMethod: Boolean
  get() = this != null && allMethods.any { !it.value.isUnlisted }

internal val Member.isUnlisted: Boolean
  get() = annotations.isUnlisted

internal val List<PObject>.isUnlisted: Boolean
  get() = any { it.classInfo == PClassInfo.Unlisted }

View on GitHub (pinned to f3efcbfc9b)