dagger/dagger · error

failed to parse dep ref string: %w

Error message

failed to parse dep ref string: %w

What it means

The dependency reference string (depSrcRef) could not be parsed into a module source ref by ParseRefString, which classifies refs as local paths, git URLs, or other supported forms. The wrapped inner error describes exactly why (e.g. malformed git ref, unsupported scheme, bad pin format).

Source

Thrown at core/modulesource.go:2133

) (inst dagql.ObjectResult[*ModuleSource], err error) {
	// sanity checks
	if parentSrc != nil {
		if parentSrc.SourceRootSubpath == "" {
			return inst, fmt.Errorf("source root path must be set")
		}
		if parentSrc.ModuleName == "" {
			return inst, fmt.Errorf("module name must be set")
		}
	}

	parsedDepRef, err := ParseRefString(
		ctx,
		NewModuleSourceFS(bk, parentSrc),
		depSrcRef,
		depPin,
	)
	if err != nil {
		return inst, fmt.Errorf("failed to parse dep ref string: %w", err)
	}

	switch parsedDepRef.Kind {
	case ModuleSourceKindLocal:
		if parentSrc == nil {
			// it's okay if there's no parent when the dep is git, but we can't find a local dep relative to nothing
			return inst, fmt.Errorf("local module dep source path %q must be relative to a parent module", depSrcRef)
		}

		if filepath.IsAbs(depSrcRef) {
			// they need to be relative to the parent module's source root
			return inst, fmt.Errorf("local module dep source path %q is absolute", depSrcRef)
		}
		if parentSrc.Workspace.Self() != nil {
			depPath := filepath.Join(parentSrc.SourceRootSubpath, depSrcRef)
			if !filepath.IsLocal(depPath) {
				return inst, fmt.Errorf("local module dep source path %q escapes workspace", depSrcRef)
			}

View on GitHub (pinned to 82ba2681db)

Solutions

1. Read the wrapped %w error to see the exact parse failure and correct the ref string in dagger.json or the API call.
2. Use a valid relative local path (e.g. "../my-dep") or a well-formed git URL (e.g. "github.com/org/repo") for the dependency.
3. If a pin is supplied, make sure it matches what the ref expects (commit SHA for git pins).
4. Re-run `dagger develop` / reload the module after editing dagger.json so the new refs are re-parsed.

Example fix

// dagger.json before
{"dependencies": [{"name": "utils", "source": "httpsgithub.com/org/utils"}]}
// after
{"dependencies": [{"name": "utils", "source": "github.com/org/utils"}]}

// validate the dep ref shape before resolving
if !(strings.Contains(depRef, "/") && !filepath.IsAbs(depRef) || strings.Contains(depRef, ".")) {
    return fmt.Errorf("dep ref %q is neither a valid relative path nor git URL", depRef)
}

inst, err := core.ResolveDepToSource(ctx, bk, dag, parentSrc, depRef, pin, depName)
if err != nil && strings.Contains(err.Error(), "failed to parse dep ref string") {
    log.Fatalf("check the dependency source in dagger.json: %v", err)
}

When it happens

Trigger: Resolving a dependency declared in dagger.json (dependencies/SDKs) or passed to ModuleSource APIs where the ref string is malformed: wrong git URL syntax, unparseable ref like 'https:/broken', invalid pin/version format, or a path that cannot be resolved against the parent's filesystem.

Common situations: Typo in a dependency entry in dagger.json; using a Windows-style or absolute path where a relative local path or git URL is expected; copying a ref with missing scheme slashes; a pin string that isn't a commit SHA or tag the parser accepts.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• failed to get caller implementation-scoped module: %w
• failed to get caller implementation-scoped module digest: %w
• schema: %w
• load dependency schema: %w
• build scale-out module query: missing module

AI-assisted analysis of dagger/dagger@82ba2681db (2026-09-05). Data as JSON: /api/errors/275130ec0c82c7c2. Report an issue: GitHub.