dagger/dagger · error

failed to parse ref string: %w

Error message

failed to parse ref string: %w

What it means

ParseRefString could not classify a module ref string as local or git. The fast path check failed, the path did not exist as a local directory, and ParseGitRefString failed with a non-endpoint error, so Dagger cannot determine what the ref string refers to.

Source

Thrown at core/modulerefs.go:110

	// Parse scheme and attempt to parse as git endpoint
	parsedGitRef, err := ParseGitRefString(ctx, refString)
	switch {
	case err == nil:
		return &ParsedRefString{
			Kind: ModuleSourceKindGit,
			Git:  &parsedGitRef,
		}, nil
	case errors.As(err, &gitref.EndpointError{}):
		// couldn't connect to git endpoint, fallback to local
		return &ParsedRefString{
			Kind: ModuleSourceKindLocal,
			Local: &ParsedLocalRefString{
				ModPath: refString,
			},
		}, nil
	default:
		return nil, fmt.Errorf("failed to parse ref string: %w", err)
	}
}

type ParsedLocalRefString struct {
	ModPath string
}

// ParsedGitRefString pairs the pure parsed git-ref data (gitref.Parsed) with
// the dagql-aware GitRef resolution that needs the engine schema.
type ParsedGitRefString struct {
	gitref.Parsed
}

func ParseGitRefString(ctx context.Context, refString string) (ParsedGitRefString, error) {
	parsed, err := gitref.Parse(ctx, refString)
	return ParsedGitRefString{parsed}, err
}

View on GitHub (pinned to 82ba2681db)

Solutions

1. Check the ref string for typos and use the correct format: a local directory path or a full git URL like https://github.com/org/repo
2. If it is a local module, run from (or pass a path to) the directory containing dagger.json
3. If it is a git module, verify the clone URL parses as a valid git endpoint and test `git ls-remote <url>`
4. Check dagger version; ref parsing rules changed across releases, so upgrade if the ref format is documented for a newer CLI

Example fix

// before
dagger call --mod github.com/org/repo/subdir fn
// after (correct git ref format with scheme)
dagger call --mod https://github.com/org/repo fn

// Go: check ref before calling dagger
func validModuleRef(ref string) bool {
	if st, err := os.Stat(ref); err == nil && st.IsDir() {
		return true
	}
	return strings.HasPrefix(ref, "https://") || strings.HasPrefix(ref, "http://")
}

if _, err := os.Stat(ref); err == nil && isGitURL(ref) { /* ambiguous: prefer explicit local ./ prefix */ }

if err != nil && strings.Contains(err.Error(), "failed to parse ref string") {
	return fmt.Errorf("module ref %q is neither a local dir nor a valid git URL", ref)
}

When it happens

Trigger: Calling dagger with a module ref string (e.g. in `dagger mod use` or `dagger call --mod`) that is neither an existing local directory nor a parseable git URL — e.g. a typo'd path, a malformed git URL with a bad scheme, or a ref that hits a parse error rather than a connection error.

Common situations: Typos in module paths, referencing a module by shorthand when cwd is not the module root, malformed git URLs (e.g. 'git@...' forms or missing scheme) that fail parsing instead of endpoint resolution.

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 resolve git tags: %w
• matching version to tags: %w
• failed to resolve git src: %w
• module source is not a git module: %s
• cannot add local module source to git module source config

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